mcp-env-doctor
Provides validation of dotenv environment files by comparing .env against .env.example, reporting missing, empty, duplicate, undocumented, or type-mismatched keys, unchanged placeholders, syntax issues, invalid type directives, and secret-like example values without exposing secret values.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
mcp-env-doctor
A safe MCP server for coding agents. It compares .env with .env.example, finds missing keys, and checks variable types, without ever putting secret values into the LLM context.
Agents like Claude Code often need to debug "why does my app not start?" and the usual answer is cat .env, which sends every secret to the model provider. mcp-env-doctor answers the same questions with key names, line numbers and issue codes only.
Quickstart
Requires uv. Nothing to install: uvx downloads and runs the tool straight from GitHub.
Check your .env from the terminal (run it in the project root):
uvx --from git+https://github.com/Maksim228gagawaga/mcp-env-doctor mcp-env-doctor checkAdd it to Claude Code as an MCP server:
claude mcp add env-doctor -- uvx --from git+https://github.com/Maksim228gagawaga/mcp-env-doctor mcp-env-doctor serveOr add it to any MCP client via .mcp.json:
{
"mcpServers": {
"env-doctor": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/Maksim228gagawaga/mcp-env-doctor",
"mcp-env-doctor",
"serve"
]
}
}
}The server inspects the directory it is started in. Pin another project root with serve --root <dir>.
Prefer pip? pip install git+https://github.com/Maksim228gagawaga/mcp-env-doctor installs the same mcp-env-doctor command.
Related MCP server: vault-mcp
What it reports
Issue code | Meaning |
| declared in the example, absent from |
| required key is present but empty |
| value does not match the declared or inferred type |
|
|
| in |
| key defined twice |
| malformed line (line number only, never the content) |
| the example file seems to contain a real key (AWS, GitHub, Stripe, JWT, high-entropy strings…) |
| an |
Declaring types
Put directives in comments directly above a key in .env.example (see examples/.env.example):
# @type enum(development|staging|production)
APP_ENV=development
# @type port
PORT=3000
# @secret
STRIPE_SECRET_KEY=
# @optional
# @type bool
DEBUG=falseTypes: string, int, float, bool, port, url, email, uuid, json, enum(a|b|c).
Keys are required unless marked @optional. Without @type, the type is inferred from the example value (3000 → int, DB_PORT=5432 → port, https://… → url). A mismatch against a declared type is an error; against an inferred type only a warning.
MCP tools
All tools are read-only:
check_env(env_file=".env", example_file=".env.example", strict=false)list_keys(...): type, required/secret flags andset | empty | missingstatus per keysuggest_missing(...): paste-ready template for missing keys; secret-looking defaults are blanked
Use it in CI
uvx --from git+https://github.com/Maksim228gagawaga/mcp-env-doctor mcp-env-doctor check --env .env.ci --example .env.example --strict --format jsonExit code: 0 ok, 1 problems found, 2 usage/path error.
Add --example-only to lint just .env.example (syntax, @type directives, real-looking secrets) when no .env exists, which is the usual situation on a CI runner.
pre-commit
Use mcp-env-doctor as a pre-commit hook straight from this repository:
repos:
- repo: https://github.com/Maksim228gagawaga/mcp-env-doctor
rev: v0.1.0
hooks:
- id: env-doctor-example # lint .env.example, block secrets committed into it
- id: env-doctor # also compare your local .env against itBoth hooks run only when a .env.example is part of the commit and never print values. env-doctor-example needs no .env, so it is safe for every contributor; env-doctor needs a local .env and fails without one.
For a monorepo, pass paths with args (and widen files if your file names differ):
- id: env-doctor
args: [--env, apps/web/.env, --example, apps/web/.env.example]Make the guarantee real
The server cannot stop an agent from reading .env with its own file tools. Pair it with a deny rule, for example in Claude Code .claude/settings.json:
{
"permissions": {
"deny": ["Read(./.env)", "Read(./.env.local)", "Read(./.env.production)"]
}
}How values are kept out
Report strings are built only from key names, line numbers, type names and issue codes. Validators return booleans, never messages containing input.
Syntax errors report a line number, nothing else; parsed entries hide values from
repr().Files are restricted to dotenv-style names (
.env,.env.*,*.env) inside--root; absolute paths,..and symlinks leaving the root are rejected, so the server can't be used as a generic file reader.The test suite includes a canary test: a fake secret planted in every position (values, malformed lines, duplicates, quotes) must not appear in any API or CLI output.
See SECURITY.md for limits.
Development
pip install -e ".[dev]"
ruff check .
pytestThe core (parser, types, checker) is stdlib-only; only server.py needs the mcp package.
License
MIT
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Checks AI-written code for leaked keys and made-up packages, on your machine. Never uploads code.
Enforces architectural invariants and code quality rules inside your AI agent's edit loop.
Lets coding agents check their own code for leaked secrets, risky dependencies and AI-code mistakes
Research-backed lint + generation for agent context files (CLAUDE.md, AGENTS.md) + prompt enhancer.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI coding agents to verify code against YAML specifications, detecting missing fields, extra fields, and type mismatches to prevent silent drift before commits.3MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI coding agents to securely inject API keys and secrets into environment files, configs, or commands without the agent ever seeing the secret values.10 npmMIT
- AlicenseAqualityCmaintenanceCompares a project's .env file against its .env.example template to surface missing, extra, and empty keys, flag empty required variables, and produce paste-safe key inventories for tickets or sharing. Runs entirely on local files with every value redacted, so secrets are never echoed or uploaded.3MIT
- AlicenseNot gradedqualityBmaintenanceEnables scanning a repository's source files for actual environment variable reads and diffing those names against .env.example or .env.sample. Returns a deterministic JSON report with the sync verdict, counts, and findings for used-but-undocumented, documented-but-unused, and missing-example vars, without ever reading values.60 npmMIT