MCP Security Guard

A Claude Code plugin that audits the MCP servers you have installed. Your code is covered by other tools. This one checks the servers that inject text into Claude's context.

It discovers servers from every place Claude Code and Claude Desktop load them: user, local and project scope, servers shipped inside installed plugins and plugins synced from your claude.ai account (named <plugin>:<server>), claude_desktop_config.json and Claude Desktop extensions, the organisation-managed managed-mcp.json, other clients on the machine (Cursor, VS Code, Windsurf, user and project configs), and the claude.ai connectors you have used (names only: their configuration lives in your account).

It scans everything a server puts into Claude's context, not only tools: server instructions, prompts, resources and resource templates go through the same poisoning checks and are pinned for rug-pull detection.

Everything runs locally. Nothing is sent anywhere.

OWASP MCP Top 10 coverage

Every finding is tagged with its OWASP MCP Top 10 id, in reports and in SARIF.

What a local tool cannot do (planned for a hosted Team plan): org-wide discovery and audit aggregation, and OAuth scope review.

Measured: detects 26/27 attacks from a corpus of publicly documented techniques, with 0 false positives on 13 hard benign samples and on 17 real servers (83 tools). See bench/RESULTS.md.

Install

/plugin marketplace add petrovicistefan/mcp-security-guard
/plugin install mcp-security-guard@mcp-security-guard

Then run /mcp-audit, or ask Claude "are my MCP servers safe?".

Other MCP clients (Cursor, VS Code, Windsurf, Claude Desktop, Cline, ...)

The same server is published on npm and runs with no install step:

{ "mcpServers": { "mcp-security-guard": { "command": "npx", "args": ["-y", "mcp-security-guard"] } } }

The command line tool is the same package: npx mcp-security-guard audit --project-only. It is also listed in the official MCP Registry as io.github.petrovicistefan/mcp-security-guard.

Team plan (paid, opt-in)

Team keys are issued by hand for now: write to me. With a team API key (MCP_SECURITY_API_KEY, or the key setting of the plugin) the plugin can also work with your organisation. Everything below is off without a key, and the free plugin stays fully functional.

• Central policy. An admin pushes one policy (allowed and blocked servers, remote hosts, plugins, pinned versions). Every member's plugin fetches it at session start (at most hourly, cached, enforced even when offline) and enforces it next to their own and the project's policy: a repository's .mcp-security.json cannot loosen it.
• Approved plugins. allowedPlugins and blockedPlugins in a policy are enforced in audits, CI and at session start; a blocked plugin is critical, an unlisted one high.
• Fleet inventory, only with consent. team report sends which servers and plugins you run: names, scopes, transport, package names and versions or remote hostnames, pinned or not. Never paths, arguments, environment, headers, query strings or secrets. Reports are refused until an admin turns fleet visibility on, team report --dry-run shows exactly what would be sent, and sending at session start needs MCP_SECURITY_TEAM_REPORT=on.
• Approval flow. team request server project:linear asks the admin; team approve adds it to the policy's allow list for everyone. Alerts (new request, new violation, policy change) go to a Slack-compatible webhook.
• Keys and seats. An admin creates a key per developer (team keys create ana, shown once; only its hash is stored) and revokes it (team keys revoke); a purchase sets the seat limit. The same admin actions are in the web dashboard (/v1/team/dashboard on the service: fleet, approvals, policy, keys, settings; the key is typed in, kept in the browser tab only, and every value from the service is written as text).
• Alerts by email (team settings --email you@example.com) next to the Slack-compatible webhook; at most 20 a hour per organisation.
• Compliance evidence. team compliance --output report.md (admin) writes a Markdown report from the policy, the latest fleet reports and the approval log: controls mapped to the OWASP MCP Top 10, each met or gap with its evidence, plus violations, stale reports and pending approvals. Together with bom (agent bill of materials) it is what an auditor asks for.
• Admin actions are CLI only (team approve, reject, policy-push, settings, inventory), not MCP tools, so injected text cannot trigger them. The MCP tools team_status, request_approval and team_report ask for confirmation and cannot approve anything.

mcp-security-guard team status
mcp-security-guard team report --dry-run
mcp-security-guard team request plugin some-plugin --note "for the docs site"
mcp-security-guard team approvals --status pending      # admin
mcp-security-guard team approve apr_… --note ok          # admin
mcp-security-guard team policy-push policy.json          # admin
mcp-security-guard team keys create ana                  # admin: a key for a developer, shown once
mcp-security-guard team settings --fleet on --webhook https://hooks.slack.com/… --email alerts@acme.example   # admin

Tools

Session-start check

A SessionStart hook re-verifies only the servers you have pinned (pinning is your consent to launch them) and stays silent unless something changed. Control it with MCP_SECURITY_SESSION_CHECK:

• full (default): compare launch configs and re-list tools
• config: compare launch configs only, launch nothing
• off: disable the check

CI / GitHub Action

Fail pull requests that add risky MCP servers to .mcp.json, and show the findings in GitHub code scanning:

name: MCP security
on: [pull_request]
permissions:
  contents: read
  security-events: write
jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: petrovicistefan/mcp-security-guard@main
        id: mcp
        with:
          fail-on: high          # critical | high | medium | low | info | none
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: ${{ steps.mcp.outputs.sarif-file }}

To also fail pull requests that add a poisoned skill, command or CLAUDE.md to the repository, set context: true on the action (second SARIF file in context-sarif-file). The same checks run locally without Claude:

node plugin/dist/cli.mjs audit --project-only --format sarif --output mcp.sarif
node plugin/dist/cli.mjs analyze-tools tools.json --name my-server   # for MCP server authors: a saved tools/list result

Scan the skills, commands, subagents and CLAUDE.md files next to your servers (add --project-only for a repository you are about to trust):

node plugin/dist/cli.mjs audit-context --project-only --fail-on high

Pin what you have reviewed with node plugin/dist/cli.mjs pin-context (or ask Claude to run pin_context); from then on audit-context and the session-start check report any pinned plugin, skill, command or CLAUDE.md that changed.

Quoted attack phrases inside examples or fenced code are reported as medium (documentation), install snippets such as curl … | sh as low; the same patterns in scripts, hooks and inline ! commands are high.

Check a server before installing it (launches it, sends only initialize and tools/list):

node plugin/dist/cli.mjs scan some-server.mcp.json --confirm-launch

Test your own server for command injection and path traversal (it calls the tools; run a test instance, ideally in a container):

node plugin/dist/cli.mjs adversarial my-server.mcp.json --server my-server --i-own-this-server --confirm-launch

Fix what the audit found (dry run first, then --write):

node plugin/dist/cli.mjs fix --pin-versions            # npx pkg → pkg@x.y.z, uvx pkg → pkg==x.y.z (looks up npm/PyPI)
node plugin/dist/cli.mjs fix --env-refs --write        # literal secrets in .mcp.json → ${VAR} references
node plugin/dist/cli.mjs fix --permissions --confirm-launch --write   # permissions.ask rules for risky tools

Start a team policy from the servers configured today:

node plugin/dist/cli.mjs policy-init && git add .mcp-security.json

Any command takes --format markdown|json|sarif|html. The HTML report is a single self-contained file you can open in a browser or attach to a ticket.

Exit codes: 0 clean, 1 findings at or above --fail-on, 2 usage error.

Limitations

Remote servers that require OAuth (most hosted MCP servers) cannot be scanned at the tool level: the scanner cannot reuse Claude Code's tokens. Their configuration is still audited.

Interactive dashboard (MCP App)

security_dashboard is an MCP App: hosts that support MCP Apps (Claude Desktop, claude.ai, VS Code Copilot…) render it inline. It shows every server with its score and grade, findings filterable by severity and server, the OWASP MCP Top 10 breakdown, recommended permission rules, and Full scan and Pin buttons. Selecting a server tells Claude what you are looking at, so follow-up questions have context. Claude Code in a terminal gets the text summary instead.

To use it in Claude Desktop, add the server to claude_desktop_config.json and ask Claude to "open the MCP security dashboard":

{ "mcpServers": { "mcp-security-guard": { "command": "node", "args": ["/path/to/mcp-security-guard/plugin/dist/index.mjs"] } } }

The UI is a single self-contained HTML file. Server-supplied text reaches the page only as text (never as HTML), and the host's sandbox applies. Develop it with a local host that drives the real server: npm run dashboard:dev -- /path/to/project.

Runtime hooks

The hooks add about 40 ms per MCP call.

Trust model

• Read-only, apart from the pin file, the audit log, and policy-init (which writes a file you asked for).
• Network only when you opt in: check_supply_chain / --supply-chain send package names and versions to npm, PyPI and OSV. The adversarial_test tool is the only one that calls tools.
• Evidence from scanned servers is sanitised (invisible characters revealed, length capped) and labelled as untrusted data.
• Secrets are masked in all output.
• Static checks reduce risk. They do not prove a server safe: malicious behaviour in tool responses or server code is out of scope.

Development

npm install
npm run build      # bundles to plugin/dist/ (committed, so the plugin runs without npm install)
npm test
npm run bench      # false-positive gate on real servers (network; Docker images optional, see bench/RESULTS.md)

test/fixtures/poisoned-server.mjs is a deliberately malicious server used by the end-to-end test.

Pro & Team (early access)

Everything above is free and stays free: it runs locally and needs no account. Paid plans add what needs a server: a daily threat feed of known malicious MCP servers, packages and skills, alerts when a server you use ships changed tool descriptions, history, and team policies, approvals and a dashboard. They are opt-in through MCP_SECURITY_API_KEY; see PRIVACY.md for exactly what is sent.

Paid plans are not on sale yet, and there is no checkout. If you or your team would like one, write to hello@petrovicistefan.ro or join the early access list: I issue keys by hand for now, and early users get launch pricing, including a limited lifetime license.

Security, privacy, license

• Found a vulnerability? See SECURITY.md.
• What is read, written and sent: PRIVACY.md.
• Changes: CHANGELOG.md.
• MIT, see LICENSE.

About the author

I'm Stefan Petrovici: passionate about IT, a husband and a father. I built mcp-security-guard on my own. I'm looking for a job.

I build web applications end to end, frontend, backend, APIs and deployment, and I'm happy to work on anything else that needs building. This repository shows how I work: tests, CI, careful documentation and attention to security.

I also build WordPress and WooCommerce plugins, available at pluginsforstores.com.

If your team is hiring, write to me at hello@petrovicistefan.ro.