Skip to main content
Glama
mcp-env-doctor

mcp-env-doctor

README.md
[![CI](https://github.com/Maksim228gagawaga/mcp-env-doctor/actions/workflows/ci.yml/badge.svg)](https://github.com/Maksim228gagawaga/mcp-env-doctor/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)

# 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](https://docs.astral.sh/uv/getting-started/installation/). Nothing to install: `uvx` downloads and runs the tool straight from GitHub.

Check your `.env` from the terminal (run it in the project root):

```bash
uvx --from git+https://github.com/Maksim228gagawaga/mcp-env-doctor mcp-env-doctor check
```

Add it to Claude Code as an MCP server:

```bash
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`:

```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.

## 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`](examples/.env.example)):

```dotenv
# @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

```bash
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](https://pre-commit.com) hook straight from this repository:

```yaml
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):

```yaml
      - 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`:

```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](SECURITY.md) for limits.

## Development

```bash
pip install -e ".[dev]"
ruff check .
pytest
```

The core (`parser`, `types`, `checker`) is stdlib-only; only `server.py` needs the `mcp` package.

## License

MIT