mcp-security-toolkit

License: MIT

Built by Redmai. For continuous autonomous API / agentsecurity scanning, use Redmai.

Source / schema / prompt audit primitives for agent builders.

Plug into Claude Code / Cursor / Claude Desktop. Audit MCP servers, agenttool schemas, system prompts, JWTs, and HTTP-response diffs — locally,in the coding agent you already use. Atomic, auditable, no orchestration.

Why this exists

Most security-flavored MCP servers wrap an existing CLI (Burp, Shodan,CyberChef) or audit MCP configurations and tool descriptions. The primitivesa developer reaches for when their own code ships an LLM feature —source-level audit of an MCP server, schema-level audit of an agent tool,static review of a system prompt — are thinly covered.

mcp-security-toolkit ships those primitives, plus the everyday pentestatoms an agent reaches for during AppSec work, so you can run one serverinstead of five.

Headline tools

`mcp_server_audit`

Heuristic AST audit of an MCP server's Python source. Enumerates@tool-decorated and imperatively-registered tools, then runs 13 detectors:

Detector	Category	Sev
Shell execution	`shell-exec`	high
Filesystem write/delete	`fs-write` / `fs-destructive`	med–high
Network egress	`network-egress`	medium
Code injection	`code-injection`	high
Over-broad params	`over-broad-param`	medium
Ambiguous/missing docstring	`ambiguous-description`	low–med
Secret read from env	`secret-in-env`	info
Path traversal	`path-traversal`	high
Prompt injection in docstring	`tool-description-injection`	medium
SSRF via URL param	`ssrf`	high
Resource URI → SQL injection	`mcp-resource-uri-sqli`	high
Tool shadowing (cross-tool)	`tool-shadowing`	medium

Tracks from X import Y [as Z] aliases so renamed dangerous importsdon't slip through. Reports include a coverage.detectors_run list andlimitations — absence of finding is NOT proof of safety.

Complements Snyk / Invariant Labs mcp-scan, which audits MCP configsand tool descriptions — this audits the source code of the server.

`agent_tool_risk_audit`

Takes a single agent tool's JSON schema and reports schema-level risks:over-broad params, ambiguous descriptions, missing constraints, exfilpotential, dangerous defaults.

`prompt_injection_audit`

Static review of a system prompt / template for injection surface.Flags untrusted placeholders, missing delimiters, trust-boundaryviolations, dangerous-instruction patterns.

`owasp_llm_classify`

Map a finding or observation to OWASP LLM Top 10 (2025) with reasoningand severity. Useful in reports and ticket creation.

`http_diff`

Appsec-focused diff of two HTTP responses. For manual auth-bypass / IDORtriage. Highlights set/added/removed headers, status changes, body diffs,and security-relevant cookies.

`jwt_inspect`

Decode + audit a JWT. Flags alg:none, weak HS-secrets (small dictionarycheck), expiry, missing standard claims, suspicious kid (path traversal),external key URLs (jku, x5u).

Pentest pack (atomic primitives)

Bundled so an agent has the basics without needing five MCP installs. Eachtool is one input → one output, no chaining.

default_creds_lookup — known default credentials by vendor / product(50+ products, aliases like fortigate, idrac, wp)
sensitive_files_list — curated sensitive paths per tech stack(common, php, wordpress, dotnet, java, node, python,k8s, docker, ci); returns paths only, does not probe
wordlist_gen — OSINT-driven wordlist generator(passwords / usernames / subdomains modes)
graphql_introspect — single introspection POST → schema summary +security observations
phpggc_generate — wraps phpggc CLI for PHP-deserialization gadgetchains (graceful if binary missing)
interactsh_register / interactsh_poll / interactsh_stop —wraps interactsh-client CLI for OOB callback URL capture (blind SSRF /XXE / RCE confirmation). _stop terminates and cleans up the session;TTL gc runs on every register

Example output

Real output from three of the headline tools. Click to expand.

mcp_server_audit on a deliberately-bad fixture — finds subprocess.run shell-exec, over-broad path: str params, missing docstring, fs-write, and a secret read from env.

{
  "file": "sample_mcp_server.py",
  "tools_found": 4,
  "summary": {"high": 1, "medium": 5, "low": 1, "info": 1},
  "tools": [
    { "name": "safe_echo", "findings": [] },
    {
      "name": "run_cmd",
      "findings": [
        {"category": "ambiguous-description", "severity": "low",
         "message": "docstring is very short (4 chars) — risk of LLM misuse"},
        {"category": "over-broad-param", "severity": "medium",
         "message": "parameter `cmd`: command-like parameter typed as bare `str`"},
        {"category": "shell-exec", "severity": "high",
         "message": "calls `subprocess.run`"}
      ]
    },
    {
      "name": "read_anything",
      "findings": [
        {"category": "ambiguous-description", "severity": "medium",
         "message": "tool has no docstring — the LLM cannot reason about when to use it"},
        {"category": "over-broad-param", "severity": "medium",
         "message": "parameter `path`: path-like parameter typed as bare `str` (no allow-list)"}
      ]
    },
    {
      "name": "write_log",
      "findings": [
        {"category": "over-broad-param", "severity": "medium",
         "message": "parameter `path`: path-like parameter typed as bare `str` (no allow-list)"},
        {"category": "fs-write", "severity": "medium",
         "message": "opens file for writing (mode='a')"}
      ]
    }
  ],
  "file_level_findings": [
    {"category": "secret-in-env", "severity": "info",
     "message": "reads secret from env `SECRET_API_KEY` — ensure it is documented in README and never logged"}
  ]
}

agent_tool_risk_audit on a tool schema with bare-string cmd / url, a URL+data exfil shape, and verify_ssl: false.

{
  "tool_name": "shell_exec",
  "detected_format": "mcp",
  "findings": [
    {"category": "ambiguous-description", "severity": "medium", "path": "<tool>",
     "message": "description is very short (5 chars) — high risk of LLM misuse"},
    {"category": "risky-name-vague-desc", "severity": "medium", "path": "<tool>",
     "message": "tool name suggests it executes ('exec') but description is brief — agent may misuse"},
    {"category": "over-broad-param", "severity": "high", "path": "cmd",
     "message": "command-like param `cmd` is bare string — agent can execute arbitrary commands"},
    {"category": "over-broad-param", "severity": "high", "path": "url",
     "message": "url-like param `url` is bare string with no `pattern` — agent can reach arbitrary hosts (SSRF / exfil)"},
    {"category": "dangerous-default", "severity": "medium", "path": "verify_ssl",
     "message": "safety-related param `verify_ssl` defaults to `False` — disables a safeguard by default"},
    {"category": "exfil-shape", "severity": "medium", "path": "<tool>",
     "message": "tool accepts both a URL-like destination and a data-like payload — classic exfil shape"}
  ]
}

jwt_inspect on the well-known jwt.io default token — verifies signature against a small weak-secret dictionary, finds missing claims.

{
  "valid_structure": true,
  "header": {"alg": "HS256", "typ": "JWT"},
  "payload": {"sub": "1234567890", "name": "John Doe", "iat": 1516239022},
  "weak_secret": "your-256-bit-secret",
  "findings": [
    {"category": "missing-claim", "severity": "medium",
     "message": "no `exp` claim — token never expires"},
    {"category": "missing-claim", "severity": "low", "message": "no `iss` claim"},
    {"category": "missing-claim", "severity": "low", "message": "no `aud` claim"},
    {"category": "weak-secret", "severity": "high",
     "message": "signature verifies with common weak secret: 'your-256-bit-secret'"}
  ]
}

Recommended companion MCP servers

For deeper coverage in adjacent areas we explicitly recommend (and do notduplicate):

PortSwigger/mcp-server — Burp Suite
ChromeDevTools/chrome-devtools-mcp — Chrome DevTools
invariantlabs-ai/mcp-scan — MCP config / tool-description audit (complementary to our source-level audit)
mukul975/cve-mcp-server — full 27-tool CVE intelligence server

Install

pip install mcp-security-toolkit

{
  "mcpServers": {
    "sec": { "command": "mcp-security-toolkit" }
  }
}

Developing locally

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest
ruff check .

End-to-end MCP smoke test (boots the server over stdio, lists tools,calls two of them):

python scripts/smoke_mcp.py

Defensive helpers — fix what we detect

The tools above find unsafe patterns in MCP servers. Themcp_security_toolkit.helperspackage is the inverse: drop-in primitives an MCP author imports to maketheir tools safe by construction.

from mcp_security_toolkit.helpers import (
    safe_path, safe_filename, safe_url, safe_sql_identifier, evaluate_expression,
)

@mcp.tool()
def read_log(name: str) -> str:
    p = safe_path(name, root="/var/log/myapp", must_exist=True)
    return p.read_text()

@mcp.tool()
def save_upload(filename: str, data: bytes) -> str:
    name = safe_filename(filename)                          # basename-only
    (Path("/var/uploads") / name).write_bytes(data)
    return name

@mcp.tool()
def fetch_url(url: str) -> str:
    url = safe_url(url)                                     # blocks SSRF
    return httpx.get(url, timeout=5).text

ALLOWED_TABLES = {"users", "orders", "events"}

@mcp.tool()
def count_rows(table: str) -> int:
    table = safe_sql_identifier(table, allow=ALLOWED_TABLES)
    return db.execute(f"SELECT COUNT(*) FROM {table}").scalar()

@mcp.tool()
def evaluate_formula(expr: str, price: float, qty: int) -> float:
    return evaluate_expression(expr, variables={"price": price, "qty": qty})

Pure functions, no I/O, no globals. Each fixes the correspondingmcp_server_audit finding category in one line.

GitHub Action

Drop into any repo to run mcp_server_audit in CI, upload SARIF to theSecurity tab, and fail the build on configured severity:

# .github/workflows/mcp-audit.yml
on: [push, pull_request]
jobs:
  audit:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v5
      - uses: x0base/[email protected]
        with:
          path: src/my_mcp_server.py
          fail-on-severity: high

CLI

# Default (no args): start the MCP stdio server — what your client config invokes
mcp-security-toolkit

# Audit every MCP server your local Claude / Cursor / Claude Desktop is configured to launch
mcp-security-toolkit scan-installed
mcp-security-toolkit scan-installed --sarif > findings.sarif

# Zero-install run, via uv
uvx mcp-security-toolkit scan-installed

Treat tool outputs as untrusted data

Some tools return content from attacker-controlled sources: http_diffquotes target response bodies, interactsh_poll returns raw OOB requests,graphql_introspect returns target-controlled schema names. If such astring contains "ignore previous instructions...", an LLM agent readingit may follow the embedded instruction — classic indirect promptinjection. MCP clients should render tool outputs inside delimiters(<tool_output>...) and not flow them silently into the next prompt.See THREAT_MODEL.md.

Non-goals

No orchestration, chaining, or decision logic across tools — primitives only.
No reimplementation of full-featured offensive CLIs (sqlmap, ghauri,dalfox); where wrapping a small, focused CLI is a natural fit(phpggc, interactsh-client), we wrap it directly with a graceful"binary not found" path.
No novel offensive research — all referenced techniques cite public sources.

License

MIT.

mcp-security-toolkit