English | 中文

safe-mcp-config

Catch risky MCP config patterns before they land in docs, issues, or public repos.

safe-mcp-config is a zero-dependency Node CLI for fast pre-share checks. It scans one or more files/directories for a small set of high-signal problems and returns predictable exit codes for CI, pre-publish gates, or review workflows.

Quick Proof

• Flags secret-looking tokens, embedded shell commands, wildcard environment passthrough, and risky absolute shell usage like bash -lc.
• Works on single files or whole directories and can emit either readable text or machine-friendly JSON.
• Redacts secret-like matches in the output so the scanner does not echo the full value back to your terminal.
• Uses stable exit codes so you can wire it into CI without wrapping it in custom scripts.

Start Here

npx safe-mcp-config ./mcp.json

If you maintain MCP examples, templates, or docs, this gives you a fast last-mile check before sharing. If it saves you from one leaked token or unsafe config pattern, star the repo.

What It Checks

• secret-looking tokens committed inline
• shell commands embedded in config values
• wildcard environment passthrough
• risky absolute shell usage such as bash -lc

Why It Exists

MCP configs are often copied between local machines, shared in issues, and pasted into docs. That makes config hygiene a real star-worthy pain point, not just an internal lint rule.

Install

Repository-local flow:

node src/cli.mjs ./mcp.json

Usage

node src/cli.mjs examples/unsafe-mcp.json

Scan multiple paths:

node src/cli.mjs config.json ./configs

Emit machine-readable JSON without failing the shell:

node src/cli.mjs --format json --fail-on none examples/unsafe-mcp.json

Fail on medium findings instead of only high findings:

node src/cli.mjs --fail-on medium examples/medium-risk-mcp.json

Scan directories that are skipped by default:

node src/cli.mjs --include-ignored .

Help and version:

node src/cli.mjs --help
node src/cli.mjs --version

CLI Options

• --format <text|json>: choose human-readable or machine-readable output
• --fail-on <none|medium|high>: control when the process exits with 1
• --include-ignored: include .git, coverage, dist, and node_modules
• --help: print usage
• --version: print package version

Exit Codes

• 0: scan completed and no findings met the configured fail threshold
• 1: at least one finding met the configured fail threshold
• 2: invalid arguments or scan errors such as missing or unreadable paths

Output Notes

Text output includes a summary, per-file findings, and a final result line. Secret-like matches are redacted in output so the CLI does not echo the full token back to your terminal.

JSON output includes:

• files: only files with findings
• errors: path-level errors
• summary: counts by severity plus exitCode

More runnable fixtures live in docs/examples.md.

Limitations

• Regex-based scanner only. It does not fully parse MCP schemas or validate command intent.
• Best-effort heuristics. It will miss some bad configs and may flag benign strings.
• Line/column reporting points to the text match, not a semantic JSON path.
• Secret detection is limited to a small set of common token formats.

Status

Early alpha. The tool stays close to zero-dependency on purpose.