MCP-Shield
MCP-Shield finds your MCP configs, connects to servers and scans tool descriptions for hidden commands, exfiltration channels and tool shadowing
- 555 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- It runs the commands of every MCP server in your settings, passing them the current process environment
- It reads the Cursor, Claude Desktop, Windsurf and VS Code configuration files, which often hold API keys
- With --claude-api-key tool descriptions are sent to the Anthropic API
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add mcp/mcp-shieldDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- It runs the commands of every MCP server in your settings, passing them the current process environment
- It reads the Cursor, Claude Desktop, Windsurf and VS Code configuration files, which often hold API keys
- With --claude-api-key tool descriptions are sent to the Anthropic API
This is third-party code. Review the repository files before installing.
What it does
MCP-Shield runs with `npx mcp-shield` and checks whether the MCP servers installed on your machine are poisoned. It first looks for configuration files in standard places: `~/.cursor/mcp.json`, `~/.vscode/mcp.json`, `~/.codeium/windsurf/mcp_config.json`, `claude_desktop_config.json` and the Code editor's `settings.json`. Another file is given with `--path`. For every server it finds, it then runs the configured command or opens the SSE address, connects as an MCP client with a 30-second timeout and requests the tool list. Tool descriptions and parameter schemas are checked against ready patterns. Hidden instructions: orders such as "do not tell the user", the tags `<instructions>`, `<important>`, `<system>`, `<secret>`, "ignore previous instructions". Sensitive file access: the `~/.ssh` directory, `.env`, `id_rsa`. Shadowing of other tools, where one description changes how another behaves, and cross-origin violations between servers. Exfiltration channels, that is, optional parameters named like `notes`, `feedback`, `metadata`, `debug`, `extra`. The result is printed as a tree of servers and tools with a HIGH, MEDIUM or LOW level and the matched fragments. With `--claude-api-key` the descriptions also go to Claude (the code names the `claude-3-7-sonnet-20250219` model) for analysis against the same five signs. `--safe-list` excludes trusted servers from the scan and from cross-origin detection. `--identify-as` makes the scanner pose as another client, for example `claude-desktop`, to check whether a server behaves differently for different clients.
Who it is for. For developers and security specialists who connect third-party MCP servers to Cursor, Claude Desktop, Windsurf and VS Code and want to check their descriptions before an agent trusts them.
Good fit when
- Before adding a new MCP server you need to check its tool descriptions for hidden orders to the agent
- Every so often you want to go through all servers in the Cursor, Claude Desktop or Windsurf settings
- After an MCP server update you need to confirm its tools gained no new parameters for leaking data
- You are writing your own MCP server and want to check that its descriptions do not look like an attack
- You want to compare how a server answers under different client names and spot behavior swapping
Not a fit when
- Running the servers from your settings is unsafe: the scanner executes their commands on your machine with your environment, so run an untrusted server in an isolated environment first
- You need checks while an agent works: the scanner reads only descriptions and does not intercept calls, and the catalog has HOL Guard for that
- You need static YARA rules and analysis of the server code: the scanner reads only descriptions and parameter schemas, while Cisco's mcp-scanner uses YARA
- Freshness matters: the last repository changes date from April 2025, and the rule patterns in the code are not updated
Example request
Run mcp-shield on my Cursor settings and show which servers have hidden instructions in their descriptionsMCP
Limitations
- MIT license. The last commit dates from April 2025, the package version is 1.0.4 and the repository has no tests.
- The scanner starts the MCP servers from your settings and passes them the whole current process environment, including secrets in environment variables. For SSE addresses it opens a connection to the server. If a server's command is dangerous, the scan will run it.
- The rules are regular expressions over description text and a list of suspicious parameter names. A new attack that does not look like the patterns will be missed. A harmless description with a phrase such as "always include" can trigger a false positive.
- The extra analysis needs an Anthropic key, and the Anthropic API is unavailable from Russia. Without a key only the patterns run. A key given on the command line stays in your shell history.
- The `--identify-as` flag changes only the client name on connection. The scanner does not compare server answers to different names itself: matching the results of separate runs is up to you.
- The repository contains the training malicious servers `bad-mcp-server.js` and `mcp-whatsapp.js` for testing the scanner, and they should run only in an isolated environment.
How to disable. There is no persistent process: the scanner runs while the command runs and writes nothing into agent settings. If you installed it globally, remove the package with `npm uninstall -g mcp-shield`. `npm cache clean --force` clears the `npx` cache.
FAQ
Which settings files does the scanner find on its own?
It checks `~/.cursor/mcp.json`, `~/.vscode/mcp.json` and `~/.codeium/windsurf/mcp_config.json`. On macOS and Windows it adds `claude_desktop_config.json` in the Claude data folder and the Code editor's `settings.json`, and on Linux only the Code editor's `settings.json`. Give other paths with `--path`.
What is a cross-origin violation?
It is a case where one server's tool description tries to change how another server's tool works, for example redirecting messenger messages. The scanner looks for mentions of popular servers (whatsapp, slack, github, gitlab, gdrive) in other tools' descriptions. Servers in `--safe-list` do not take part in that check.
Why does it need an Anthropic key?
With a key, a model additionally analyzes the tool descriptions against five signs: hidden instructions, sensitive file access, tool shadowing, data exfiltration and behavior override. The overall verdict is printed next to the pattern verdict as AI Risk Level. Without a key only the pattern analysis remains.
How do I check whether a server changes by client name?
Run the scanner twice: first under the default name, then with `--identify-as claude-desktop` or another client name, and compare the tool lists and descriptions. The author calls this a check for possible bait-and-switch. The scanner does not compare the runs automatically.
What is the scanner built on and what are its dependencies?
It is a Node.js package in TypeScript with `@modelcontextprotocol/sdk` for connecting to servers and `@anthropic-ai/sdk` for the optional analysis. Output is formatted by `chalk`, `ora` and `boxen`. Configs are read through `json5` and `fs-extra`.
Discussion
No questions or reviews yet.
Related
MCP serversAgentShield audits the .claude folder for plaintext keys, broad permissions, dangerous hooks and risky MCP servers and grades the setup from A to F
An MCP server that gives the agent vulnerability triage: NVD data, EPSS, the CISA KEV catalog, MITRE ATT&CK mapping and one-call CVE risk scoring
x64dbg MCP
x64dbg MCP Server Plugin
An x64dbg and x32dbg plugin with an MCP server of 79 tools and 11 Claude Code commands for crash analysis, tracing and memory dumps
An offensive security MCP server: the agent runs 150+ pentest and recon tools and drives automated target assessments
MCP Scanner
mcp-scanner
A scanner from Cisco AI Defense: checks MCP servers and their tools for threats with three engines, YARA rules, a model and the Cisco API
A security scanner for AI-written code: secrets, dependencies, MCP and CI, findings investigated with evidence, and fixes you approve
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Repository stars | Main difference |
|---|---|---|---|
| MCP-Shield (this entry) | no | 555 | |
| MCP Scanner | yes | 1,094 | Cisco AI Defense's scanner with three engines: YARA rules, a model and the Cisco API |
| HOL Guard | yes | 951 | checks agent actions while it works rather than server descriptions and waits for your decision on risky calls |
README in short
The repository has a description with commands and flags, a sample output with a server tree and one analyzed finding, and lists of features and use cases. Four attack types are shown with short code examples: description poisoning, shadowing another tool, an exfiltration channel and a cross-origin violation. The `mcp-servers-example` folder holds two training servers for testing the scanner, and the end links to the Invariant Labs research the project builds on.