io.github.CloudCorpRecords/mcpaudit

mcpaudit

Point it at any MCP server. Get a score, and the receipts.

The MCP Registry is filling up with servers nobody has ever audited. A server can list tools with no descriptions (so models never call them correctly), schemas that contradict themselves (required fields that don't exist), or — the dangerous one — cheerfully return success when you call a tool that doesn't exist. None of that shows up until a user's agent does something weird in production.

mcpaudit launches the server the way a real client does, runs the full handshake, inspects every tool, deliberately makes a bad call, and prints one scored report with named, evidence-backed issues. No LLM anywhere in the audit: every check is deterministic and repeatable.

What it checks

Scoring: start at 100, each error costs 8, each warning costs 3. Verdicts: PASS (clean), WARN (works, but the issues will cost it users or correctness), FAIL (error-severity issues), UNREACHABLE (the handshake never completed — reported with the launch error, never a guessed score).

mcpaudit audits stdio servers. Remote (HTTP) servers — config entries with a url, or a URL passed as the command — are reported as UNREACHABLE with that explanation, never silently skipped and never spawned.

New in 0.1.1, from the first real-production validation battery (25+ external servers, three runs each, findings hand-checked against raw ground truth): server arguments starting with -- pass through verbatim (see Usage), prompt/resource-only servers pass, the default per-step timeout is 60s so npx/uvx cold starts are not mistaken for dead servers, and --json always emits one parseable document.

Usage

CLI

# Audit a server by its launch command
npx @reneturcios/mcpaudit audit npx -y @reneturcios/shipcheck mcp
npx @reneturcios/mcpaudit audit node dist/cli.js mcp

# Audit every server in an MCP client config (or one named entry)
npx @reneturcios/mcpaudit audit --config ~/.claude/claude_desktop_config.json
npx @reneturcios/mcpaudit audit --config ./mcp.json --server greenlight

# Server arguments that start with -- pass through untouched
npx @reneturcios/mcpaudit audit uvx mcp-server-git --repository /path/to/repo

# Use a literal -- to force everything after it into the server command
# (even flags that share a name with mcpaudit's own, like --timeout)
npx @reneturcios/mcpaudit audit node server.js -- --timeout 5000

# Quoted command line, machine-readable output, custom timeout
npx @reneturcios/mcpaudit audit --cmdline "npx -y @scope/pkg mcp" --json --timeout 30000

# Offline: validate a tools/list dump without launching anything
npx @reneturcios/mcpaudit tools tools.json

Example output:

mcpaudit npx -y @reneturcios/shipcheck mcp: PASS (score 100/100, grade A)
  server: shipcheck 0.1.0 · protocol 2025-11-25 · 3 tool(s) · initialize 1813ms · tools/list 16ms
  error handling: bad tool call returned a proper error
  No issues found.
PASS: handshake, schemas, and error handling all check out.

(That is a real run, from the first MCP Server Index seed, 2026-10-22. Initialize time is measured from spawn and includes npx cold-start overhead — the report measures the launch path a user's client actually experiences, and says so.)

Exit codes: 0 for PASS/WARN, 1 for FAIL/UNREACHABLE, 2 for usage errors — CI-ready.

MCP server

Add to your MCP client config:

{
  "mcpServers": {
    "mcpaudit": {
      "command": "npx",
      "args": ["-y", "@reneturcios/mcpaudit", "mcp"]
    }
  }
}

Tools:

• audit_server: launch and audit one server from a command + args (+ optional env, timeout).
• audit_config: audit every server in a config file, or one named entry.
• audit_tools: offline validation of a tools/list array.

Docker

docker run -i ghcr.io/cloudcorprecords/mcpaudit mcp
docker run --rm ghcr.io/cloudcorprecords/mcpaudit audit node server.js mcp

The MCP Server Index

mcpaudit is the engine behind a growing public dataset, the MCP Server Index: scored audits of real, published MCP servers, run with the published binary and refreshed as servers ship. The seed — the author's own tool family, audited first because you audit yourself before you audit anyone else — lives in the 100-packages workspace and grows with every wave.

The toolkit

mcpaudit is Wave 1, package 4 of a planned family of small, single-purpose developer tools by the same author, all built the same way: one bin that serves a CLI and an MCP server, deterministic checks with evidence, no invented answers.

• greenlight: pre-flight checks for open-source contributions: is this issue actually landable?
• shipcheck: release verification — git tag, GitHub release, npm, MCP Registry, and GHCR must all agree, or NO-GO.
• cidiff: base-vs-head CI differ for PRs.
• reprocheck: red-first repro verifier.
• prwatch: attention report for your open PRs.
• claimcheck: stale-claim states and parked fixes on forks.
• gatefile: extract hidden contribution gates into machine-readable contribution-gates.json.
• pkgverdict: pre-install verdicts for npm packages: GO, RISKY, FAKE, or MISSING.

Development

npm install
npm run build
npm test   # validator/scoring unit tests + live probes against fixture servers

License

MIT