Provides a developer toolkit that automates stack detection, environment validation, port conflict checking, and documentation drift detection.
Also known as WhenLabs-org/when, @whenlabs/when
- Stars
- 4
- Tools
- 8
- Downloads, 30 days
- —
- Latest version
- 0.12.3
- Last commit
- Nov 9, 2026
- License
- MIT
What is WhenLabs MCP?
WhenLabs provides a developer toolkit that automates stack detection, environment validation, port conflict checking, and documentation drift detection. It exposes 8 tools, such as aware_sync, berth_check, envalid_validate.
Summary generated from the project's README
About WhenLabs MCP server
Automating project health checks and environment validation within Claude Code is what this toolkit enables for developers. By installing the server via npx, you integrate six specialized tools into your workflow that Claude can call automatically. The setup process registers the whenlabs server and injects a CLAUDE.md block so the AI understands how to utilize the available endpoints.
Users can manage their development environment through specific endpoints like berth_check for port conflicts or envalid_validate for verifying .env files against a schema. The toolkit also includes stale_scan to find documentation drift and vow_scan to check dependency licenses against your policies. For a complete overview of project status, the whenlabs_summary endpoint provides a unified rollup of all scanners in a single call.
Beyond simple checks, the velocity tools allow you to time coding tasks using velocity_start_task and velocity_end_task. This entire system runs locally using Node 20+ and communicates via stdio. It replaces legacy velocity-mcp registrations with a single, unified installation.
What you can do with it
- 1Detecting port conflictsAsk the AI to check if any local ports are already in use before you attempt to start a new development server.
- 2Validating environment variablesHave the AI verify that your current .env file matches the required schema to prevent runtime errors.
- 3Identifying documentation driftRequest a scan to see if your project documentation has become outdated compared to the actual source code.
- 4Auditing dependency licensesUse the AI to scan your project dependencies to ensure all licenses comply with your organization's policy.
Written from the project's README. Every use case is checked against a quote from it.
How to install WhenLabs MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall WhenLabs MCP in Claude Code
$ claude mcp add when -- npx -y @whenlabs/whenInstall WhenLabs MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"when": {
"command": "npx",
"args": [
"-y",
"@whenlabs/when"
]
}
}
}Install WhenLabs MCP in VS Code
.vscode/mcp.json
{
"servers": {
"when": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@whenlabs/when"
]
}
}
}Install WhenLabs MCP in VS Code CLI
$ code --add-mcp '{"name":"when","type":"stdio","command":"npx","args":["-y","@whenlabs/when"]}'Install WhenLabs MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"when": {
"command": "npx",
"args": [
"-y",
"@whenlabs/when"
]
}
}
}Install WhenLabs MCP in Codex
$ codex mcp add when -- npx -y @whenlabs/whenInstall WhenLabs MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.when] command = "npx" args = ["-y", "@whenlabs/when"]
Install WhenLabs MCP in Gemini CLI
$ gemini mcp add -s user when npx -- -y @whenlabs/whenInstall WhenLabs MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"when": {
"command": "npx",
"args": [
"-y",
"@whenlabs/when"
]
}
}
}WhenLabs MCP tools 8
Detected from the READMEaware_syncberth_checkenvalid_validatestale_scanvow_scanvelocity_start_taskvelocity_end_taskwhenlabs_summary
| aware_sync | — | |
| berth_check | — | |
| envalid_validate | — | |
| stale_scan | — | |
| vow_scan | — | |
| velocity_start_task | — | |
| velocity_end_task | — | |
| whenlabs_summary | — |
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledPass
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHub@whenlabs/when
Six tools. One install.
A single installable toolkit that brings six WhenLabs developer tools into your Claude Code workflow. After install, the tools are exposed over a single MCP server and Claude calls them automatically when relevant.
Install
npx @whenlabs/when install
One-time setup. The installer:
- Registers a single MCP server (
whenlabs) in your Claude Code configuration - Injects a CLAUDE.md block so Claude knows when to use each tool
- Cleans up any legacy
velocity-mcpregistration (velocity is now bundled)
The six tools
| Tool | Purpose |
|---|---|
| aware | Auto-detect stack and generate AI context files (CLAUDE.md, .cursorrules, …) |
| berth | Detect port conflicts before starting dev servers |
| envalid | Validate .env files against a schema |
| stale | Detect documentation drift between docs and code |
| vow | Scan dependency licenses and validate against policy |
| velocity | Time coding tasks and learn from historical data |
MCP tools
Eight endpoints across the six tools:
| Endpoint | What it does |
|---|---|
aware_sync |
Detect stack and regenerate AI context files |
berth_check |
Scan project for port conflicts |
envalid_validate |
Validate .env files against schema |
stale_scan |
Detect documentation drift |
vow_scan |
Scan licenses and validate against policy |
velocity_start_task |
Start timing a coding task |
velocity_end_task |
End timing and record results |
whenlabs_summary |
Unified rollup across all five scanners in one call |
All eight are served by the single whenlabs MCP server (stdio, Node 20+). Fix/init/auxiliary commands remain available via each tool's CLI (npx @whenlabs/<tool> --help).
CLI
when init # Onboard a project — detect stack, bootstrap configs, run all checks
when doctor # Run all six tools and show a unified health report
when install # Register MCP server in Claude Code
when uninstall # Remove MCP server
For per-tool operations, use the tool directly:
npx @whenlabs/stale scan
npx @whenlabs/envalid validate
npx @whenlabs/berth check
npx @whenlabs/aware sync
npx @whenlabs/vow scan
Manual MCP configuration
If you're not using the install command, add this to your Claude Code MCP config:
{
"mcpServers": {
"whenlabs": {
"command": "npx",
"args": ["@whenlabs/when", "when-mcp"]
}
}
}
License
MIT — see LICENSE
WhenLabs MCP questions
How do I add WhenLabs MCP to Claude Code?
Run claude mcp add when -- npx -y @whenlabs/when in your terminal. Add --scope user to make it available in every project.
How do I add WhenLabs MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does WhenLabs MCP provide?
It exposes 8 tools, including aware_sync, berth_check, envalid_validate, stale_scan, vow_scan.
How do I install the WhenLabs toolkit?
You can install it using the command npx @whenlabs/when install.
Can I configure the MCP server manually?
Yes, you can manually add the whenlabs server to your Claude Code MCP config using npx @whenlabs/when when-mcp.
What does the 'when doctor' command do?
It runs all six tools and provides a unified health report for your project.