mcpcheck-py 0.1.0

Lint MCP config files for Claude Desktop, Claude Code, Cursor, Cline, Windsurf, and Zed. Stdlib-only Python port of @mukundakatta/mcpcheck.

mcpcheck-py

A linter for MCP (Model Context Protocol) config files. Works on every client that reads mcp.json / .mcp.json / claude_desktop_config.json / Zed's context_servers: Claude Desktop, Claude Code, Cursor, Cline, Windsurf, Zed.

Stdlib-only Python port of @mukundakatta/mcpcheck. Catches hardcoded secrets, dangerous commands, missing transports, malformed env blocks, plaintext HTTP with tokens, and shell-metachar injection.

Note: there's a separate package called mcp-config-check on PyPI by a different author. This package is the user's own port and uses the -py suffix to disambiguate.

Install

pip install mcpcheck-py

Usage

from mcpcheck import lint

result = lint("/path/to/mcp.json")

result.fatal           # True if the file failed to parse
for issue in result.issues:
    print(issue.line, issue.severity, issue.rule_id, issue.message)

You can also lint in-memory configs:

from mcpcheck import lint_source

source = '''
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_abcdef1234567890abcdef1234567890" }
    }
  }
}
'''
result = lint_source(source, file="<inline>")

Result shape

@dataclass
class Issue:
    rule_id: str
    severity: str           # "error" | "warning" | "info"
    message: str
    json_path: str          # dotted path, e.g. "mcpServers.github.env.GITHUB_TOKEN"
    line: int = 1

@dataclass
class LintResult:
    file: str
    fatal: bool
    issues: list[Issue]

Rules

Rule id	Severity	Checks
invalid-json	error	File doesn't parse as JSON / JSONC.
empty-servers	warning	No mcpServers / servers / context_servers key, or empty.
duplicate-server-name	warning	Two servers share a case-insensitive name.
unknown-field	info	Server has a field outside the known set.
missing-transport	warning	Server has neither command (stdio) nor url (sse / streamable-http).
dangerous-command	error	sudo, curl | sh, docker --privileged, host-root mounts, rm -rf /.
hardcoded-secret	error	Provider-shaped key (OpenAI, Anthropic, GitHub, AWS, Slack, etc.) in env values.
plaintext-http-with-token	warning	http:// URL combined with a bearer/auth header.
invalid-env-var-name	warning	env key doesn't match ^[A-Z_][A-Z0-9_]*$.
empty-env-value	warning	env value is empty or whitespace.

Supported clients

mcpcheck.CLIENT_PATHS exposes the same path table the JS sibling uses, so you can build editor / CI integrations that auto-discover configs:

• cursor -- ~/.cursor/mcp.json
• claude-desktop -- ~/Library/Application Support/Claude/claude_desktop_config.json, ...
• claude-code -- ~/.claude.json, **/.mcp.json
• windsurf -- ~/.codeium/windsurf/mcp_config.json
• zed -- ~/.config/zed/settings.json
• cline -- **/.cline/mcp.json, **/cline_mcp_settings.json

API differences from the JS sibling

• Stdlib only -- JSONC (comments + trailing commas) handled by a small hand-rolled tolerant scanner instead of jsonc-parser. Strict JSON files go through json.loads directly.
• Returns a LintResult dataclass instead of the JS object literal.
• Spec entrypoint is lint(config_path) -- mirror of the spec's lint(config_path) -> LintResult. lint_source covers the in-memory case.
• Fewer rules than the full JS sibling -- the Python port focuses on the high-signal subset (secrets, dangerous commands, structure). Run the JS CLI for the full surface.

See the JS sibling's README for the broader rationale.