Mcp Config Auditor

@guardbee/mcp-config-auditor

🇬🇧 English | 🇹🇷 Türkçe | 🇨🇳 中文 | 🇯🇵 日本語 | 🇰🇷 한국어 | 🇧🇷 Português | 🇪🇸 Español | 🇩🇪 Deutsch

[npm version] [npm downloads] [License: MIT]

An MCP server that audits the MCP client config on a machine: Cursor mcp.json, Claude Desktop claude_desktop_config.json, Windsurf mcp_config.json, and VS Code mcp.json.

mcp-server-auditor reads an MCP server's source. This package reads the config that decides which servers an agent will run. It does not start those servers and it does not send the config anywhere.

Telemetry is off by default. With GUARDBEE_TELEMETRY=1 it sends the server, tool, success, duration and short parameter values such as a file path; longer strings and fields like content, token or password are replaced with a placeholder. See @guardbee/mcp-telemetry.

Claude ──► mcp-config-auditor ──► mcp.json  (or host-wide discover)              │              ├─ Unpinned package     (npx -y pkg, @latest)              ├─ Typosquat            (one edit from a known server package)              ├─ Secret in env/args              ├─ autoApprove "*"              ├─ Remote HTTP without auth              ├─ Cross-server shadowing (when you pass a tool inventory)              ├─ Agent SKILL.md (allowed-tools, body, lookalike names)              └─ Shadow MCP discover  (OWASP MCP09 — host paths + org allowlist)

Checks

Loopback URLs (localhost, 127.0.0.1, ::1) are not remote findings. Placeholder values (${API_KEY}, changeme) are not secrets. Reported secret matches are redacted. Bash(git diff:*) is a command allowlist and is not an unrestricted shell. Read alone is not flagged.

Quick start

{  "mcpServers": {    "guardbee-mcp-config-auditor": {      "command": "npx",      "args": ["-y", "@guardbee/mcp-config-auditor"]    }  }}

npx @guardbee/mcp-config-auditor scan .cursor/mcp.json --fail-on=high --format=sarif > results.sarifnpx @guardbee/mcp-config-auditor inventory ./tool-inventory.jsonnpx @guardbee/mcp-config-auditor discover --allowlist=./mcp-allowlist.json --fail-on=high

GuardBee MCP Index grades

--grades (on scan <file> and discover) shows the GuardBee MCP Index grade of every configured server: an A–F trust grade for each server in the official MCP Registry, rebuilt weekly from its published package. The grade comes from the shipped code (the GuardBee scanners), known vulnerabilities and malware (OSV), Sigstore build provenance and maintenance signals; the rubric is public and versioned. --min-grade=C also reports every server graded below C (mcp_index_grade_below_minimum, so --fail-on can gate on it).

npx @guardbee/mcp-config-auditor discover --min-grade=C#   A  filesystem  npm:@modelcontextprotocol/server-filesystem  graded @modelcontextprotocol/[email protected]#   D  notes       npm:notes-mcp                                graded [email protected] (the config runs the latest version)#   –  internal    local command: not a registry package

The whole index is downloaded (and cached for a day in ~/.guardbee/mcp-index.json) and searched on this machine, so no server or package name is sent anywhere. --offline uses the cache only; --index-url= points at another copy. Local commands, remote URLs and servers outside the official registry have no grade and are never findings.

Shadow MCP discover (MCP09)

Walks well-known Cursor / Claude Desktop / Claude Code / Windsurf / VS Code / Gemini CLI / Cline / Zed paths on this machine and compares every installed server to an organization allowlist. Does not start servers. Claude Code's per-project servers (projects["<path>"].mcpServers in ~/.claude.json) are listed under claude-code:<path>; Zed's context_servers and JSON with comments are understood.

Inventory. --format=json adds an inventory: for every server its client, config path, name, transport, command and arguments, npm/PyPI package with version and whether it is pinned, URL, the names of its env variables and headers, auto-approve, and the findings for it. It never holds a secret: env and header values are left out, argument values after --token/--api-key-style flags, KEY=value pairs, provider tokens and passwords in connection strings are [redacted], and URLs lose their credentials and query values. --format=text prints the same list; --format=sarif the findings.

Fleet. FLEET.md has Jamf, Intune, systemd and CI recipes. --allowlist-from-dashboard checks against the organization allowlist admins manage in the dashboard (merged with --allowlist when both are given), and --grades adds MCP Index grades to the uploaded inventory.

Organisation-wide. --upload sends the inventory to the GuardBee dashboard (GUARDBEE_API_KEY, a workspace key with the gateway.write scope), which keeps the latest inventory per machine; run it from your device-management tool or a login script. The machine's host name, OS and OS user name are included — --no-user leaves the user out.

GUARDBEE_API_KEY=gb_… npx @guardbee/mcp-config-auditor discover --allowlist=./mcp-allowlist.json --upload --fail-on=none

Allowlist JSON:

{  "names": ["filesystem", "github"],  "packages": ["@modelcontextprotocol/server-filesystem", "@guardbee/mcp-secret-scanner"],  "hosts": ["mcp.example.com"]}

Or lines: name:filesystem, package:@scope/pkg, host:mcp.example.com, or a bare server name.

A directory scan opens mcp.json, mcp_config.json, claude_desktop_config.json, and SKILL.md. Pass a file path to scan any other name. A file named SKILL.md is audited as an agent skill. Same-name and lookalike skill findings appear on a directory scan, because one file cannot see the others.

guardbee.yml:

mcp-config-auditor:  fail-on: high  max-files: 5000  exclude:    - "fixtures/"

Tool inventory shape:

{  "servers": [    { "name": "github", "tools": [{ "name": "create_issue", "description": "Open an issue" }] }  ]}

Shadowing needs that inventory because a client config does not list tools. rug-pull-detector can collect a live tools/list; this package compares several of those lists.

Feedback

Questions, ideas, or a false positive? Start a thread in GitHub Discussions or open an issue. If GuardBee is useful to you, a ⭐ on the repository helps others find it.