mcp-guardian is an open-source Python tool that reviews the configuration of MCP (Model Context Protocol) servers connected to AI agents and flags three kinds of risk: prompt injection hidden in tool descriptions, silent changes to those descriptions, and tools that return external content to the model without filtering. Each finding carries a CVSS score and the overall result is PASS or FAIL. Published on GitHub by the user sopitacasera, the project is very new: the repository has two commits and was last updated on 2 November 2026.
Key points about mcp-guardian in 30 seconds
- It scans MCP configuration files from Claude Desktop, Cursor or any JSON with a list of tools.
- It looks for prompt injection, tool poisoning and unfiltered return channels.
- Each finding includes severity and a CVSS score, with JSON and HTML reports.
- A CI mode fails the pipeline on high or critical findings.
- It is a very young project, licensed under Apache 2.0 according to its repository.
The problem it targets is real. Many teams add MCP servers to their agents the way people once installed browser extensions: without checking what comes with them. With MCP, the risk starts before the agent runs anything, because the model reads each tool’s description to decide how to use it. If that description hides instructions, the agent may follow them. Swiss firm Invariant Labs, acquired by Snyk in June 2025, was among the first to document attacks such as MCP tool poisoning and rug pulls.
What it detects
According to its documentation, mcp-guardian checks three vectors:
- Prompt injection: it scans descriptions and input schemas for patterns linked to known attacks, such as instruction overrides, jailbreaks, credential exfiltration commands and XSS-style markup. The author assigns it a CVSS of 9.1.
- Tool poisoning: it keeps a SHA-256 hash baseline of each description and flags any server that modifies one after the user approved it, the so-called rug pull. CVSS 8.1.
- Return channel: it flags tools such as fetch, browse or read_file that hand external content back to the model unfiltered, the path through which a web page or file can inject instructions or leak agent context. CVSS 5.9.
The third check is what the author presents as the differentiator, saying he did not find it in other public tools. It deserves some nuance: according to the README, the analysis relies on configuration flags and tool types, so it is heuristic. Knowing that a tool is called fetch and does not filter its output is a useful warning, but it does not replace reviewing how the agent handles that content. The README also compares the project with Promptfoo and MCP-Scan and stresses that it is vendor-neutral.
How to use it
Install it with pip or run it without installing via uvx:
pip install mcp-guardian
# Without installing
uvx mcp-guardian scan ~/.config/claude/claude_desktop_config.json
# HTML and JSON report
mcp-guardian scan config.json --html report.html --output report.json
# CI mode: exits with code 1 on HIGH or CRITICAL findings
mcp-guardian scan config.json --fail-on highCode language: PHP (php)It supports the Claude Desktop config file (on macOS, ~/Library/Application Support/Claude/claude_desktop_config.json), Cursor’s .cursor/mcp.json and any JSON with a list of tools. It also ships a Python SDK and a GitHub Actions example:
- name: Scan MCP configuration
run: |
pip install mcp-guardian
mcp-guardian scan .cursor/mcp.json --fail-on highBefore you trust it
A security scanner is also code that runs with access to your configuration, so it deserves the same scrutiny as any MCP server. With two commits, mcp-guardian has no track record or community behind its results yet, and the CVSS scores are the ones its author assigns to each category, not to specific registered vulnerabilities. There is also a discrepancy: the announcement shared on social media mentions an MIT license, while the repository states Apache 2.0. The sensible approach is to review the code, run it in an isolated environment and treat it as one more layer, alongside limiting agent permissions or adding CI guardrails such as brakes for GitHub.
Frequently asked questions
What is mcp-guardian?
An open-source Python scanner that checks MCP servers for prompt injection, tool poisoning and unfiltered return channels.
What is MCP tool poisoning?
An attack in which a tool description contains malicious instructions or changes after approval in order to manipulate the agent.
Can it run in CI?
Yes. With –fail-on high it exits with code 1 on high or critical findings, and the repository includes a GitHub Actions example.
What license does it use?
The repository states Apache 2.0, although some posts about the project mention MIT.
Sources: