mcp-audit

Security scanner and linter for Model Context Protocol (MCP) servers. Like npm audit and eslint, but for the tools you hand your AI agents.

npm: https://www.npmjs.com/package/@royalpinto007/mcp-audit

npm install -g @royalpinto007/mcp-audit
# or run it directly
npx @royalpinto007/mcp-audit stdio "node my-mcp-server.js"

Why

MCP servers give language models real capabilities: run commands, read files, hit internal URLs, mutate databases. A single over-scoped tool or a .env exposed as a resource turns a helpful agent into a remote code execution or data-exfiltration path. Yet most MCP servers ship with no security review at all.

mcp-audit connects to an MCP server (or lints its manifest), enumerates every tool, resource, and prompt, and runs a catalog of security rules over that surface. It finds the dangerous stuff before your agent does:

• arbitrary command / shell execution tools,
• destructive actions with no confirmation or scoping,
• prompt-injection sinks planted in tool descriptions,
• secrets and system paths exposed as resources,
• SSRF-prone URL arguments and unauthenticated HTTP transports,
• unconstrained input schemas that let the model pass anything, anywhere.

It runs offline, is fully deterministic, and drops straight into CI with JSON and SARIF output for GitHub code scanning.

Quickstart

# Audit a server you spawn over stdio
npx @royalpinto007/mcp-audit stdio "node my-mcp-server.js"

# Audit a remote server over HTTP (with a bearer token)
npx @royalpinto007/mcp-audit http https://mcp.example.com/mcp --token "$MCP_TOKEN"

# Lint a server's declared surface from a manifest, without running it
npx @royalpinto007/mcp-audit static ./mcp-manifest.json

# List every built-in rule
npx @royalpinto007/mcp-audit rules

Example output

mcp-audit — stdio target node my-mcp-server.js
server: insecure-demo-server v0.0.0-internal
surface: 5 tools, 2 resources, 1 prompts

 CRITICAL   (3)
  ✖ MCP002 Arbitrary execution tool detected  @ run_shell
      Tool "run_shell" appears to execute commands or code (matched "shell").
      fix: Avoid exposing raw exec. If unavoidable, allowlist commands, drop privileges, sandbox execution, and require human approval.
  ✖ MCP030 Resource surfaces sensitive material  @ file:///home/app/.env
      Resource "file:///home/app/.env" references ".env", which commonly holds secrets or system credentials.
      fix: Remove the resource or restrict it to non-sensitive content.

 HIGH  (4)
  ✖ MCP001 Destructive tool has no confirmation argument  @ delete_file
  ✖ MCP031 Unconstrained filesystem path argument  @ delete_file.path
  ...

20 findings   3 critical, 4 high, 5 medium, 6 low, 2 info

The process exits 1 when any finding reaches the --fail-on threshold (default high), so a failing audit breaks the build.

Rule catalog

19 built-in rules, each with a stable id, severity, and remediation. Toggle any of them via config.

Configuration

Drop a .mcpauditrc (or .mcpauditrc.json / mcpaudit.config.json) in your repo. mcp-audit discovers the nearest one walking up from the working directory.

{
  "failOn": "high",
  "disabledRules": ["MCP013"],
  "severityOverrides": {
    "MCP011": "info"
  },
  "ignore": ["fetch_url.note"]
}

Severities, lowest to highest: info, low, medium, high, critical.

CLI flags

--json                 Emit JSON instead of terminal output
--sarif                Emit SARIF 2.1.0 (for GitHub code scanning)
--output         Write the report to a file instead of stdout
--config         Use a specific config file
--fail-on    Exit non-zero at/above this severity
--disable         Comma-separated rule ids to disable
--only            Comma-separated rule ids to run exclusively
--token         Bearer token for http transport
--header          Extra header for http transport (repeatable)
--sse                  Use the legacy SSE transport for http
--no-color             Disable colored output

SARIF and CI usage

mcp-audit emits SARIF 2.1.0 so findings show up as annotations in GitHub code scanning.

- run: npx @royalpinto007/mcp-audit static ./mcp-manifest.json --sarif --output mcp-audit.sarif --fail-on critical
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: mcp-audit.sarif

Exit codes:

Static mode

Static mode lints a server’s declared surface from a JSON manifest without ever executing it, which is ideal for scanning untrusted servers in code review. A manifest is just the tools/resources/prompts the server would advertise:

{
  "transport": "http",
  "url": "https://mcp.example.com/mcp",
  "authProvided": false,
  "server": { "name": "billing-mcp", "version": "1.0.0" },
  "tools": [
    {
      "name": "charge_card",
      "description": "Charge a saved payment method.",
      "inputSchema": {
        "type": "object",
        "properties": { "amount": { "type": "number" } },
        "required": ["amount"],
        "additionalProperties": false
      }
    }
  ]
}

A bare JSON array of tools is also accepted.

Programmatic API

import { connectStdio, runAudit, DEFAULT_CONFIG, renderJson } from "mcp-audit";

const target = await connectStdio({ command: "node", args: ["server.js"] });
const result = runAudit(target, DEFAULT_CONFIG);
console.log(renderJson(result));

Development

npm install
npm run build      # compile TypeScript to dist/
npm test           # run the vitest suite (includes a live mock server)
npm run typecheck  # type-only check

The repo ships a real mock MCP server (fixtures/mock-server.mjs) so the test suite is hermetic and reproducible.

Contributing

Contributions are welcome. A good new rule is: independently coded, has a stable MCPxxx id, a clear severity and remediation, and a test that fires it against a fixture (plus one that proves it stays quiet on a clean surface). Add the rule module under src/rules/, register it in src/rules/index.ts, and cover it in test/rules.test.ts.

License

MIT © royalpinto007