Skip to main content
Glama
mcp-env-doctor

mcp-env-doctor

CI License: MIT Python 3.10+

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 check

Add 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 serve

Or 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

missing_key

declared in the example, absent from .env

empty_value

required key is present but empty

type_mismatch

value does not match the declared or inferred type

unchanged_placeholder

.env still holds the example's placeholder

undocumented_key

in .env but not in the example

duplicate_key

key defined twice

syntax_error

malformed line (line number only, never the content)

example_contains_secret

the example file seems to contain a real key (AWS, GitHub, Stripe, JWT, high-entropy strings…)

invalid_type_directive

an @type in the example is not a known type, so nothing would be enforced

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=false

Types: 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 and set | empty | missing status per key

  • suggest_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 json

Exit 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 it

Both 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 .
pytest

The 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…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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 npm
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Compares 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.
      3
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 npm
      MIT