mcp-security-toolkit

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

Source / schema / prompt audit primitives for agent builders.

Plug into Claude Code / Cursor / Claude Desktop. Audit MCP servers, agent tool 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 primitives a 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 pentest atoms an agent reaches for during AppSec work, so you can run one server instead 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:

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

Complements Snyk / Invariant Labs mcp-scan, which audits MCP configs and 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, exfil potential, dangerous defaults.

prompt_injection_audit

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

owasp_llm_classify

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

http_diff

Appsec-focused diff of two HTTP responses. For manual auth-bypass / IDOR triage. 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 dictionary check), 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. Each tool 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 gadget chains (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.

{
  "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"}
  ]
}

{
  "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"}
  ]
}

{
  "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 not duplicate):

• 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. The mcp_security_toolkit.helpers package is the inverse: drop-in primitives an MCP author imports to make their 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 corresponding mcp_server_audit finding category in one line.

GitHub Action

Drop into any repo to run mcp_server_audit in CI, upload SARIF to the Security 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/mcp-security-toolkit@v0.3
        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_diff quotes target response bodies, interactsh_poll returns raw OOB requests, graphql_introspect returns target-controlled schema names. If such a string contains "ignore previous instructions...", an LLM agent reading it may follow the embedded instruction — classic indirect prompt injection. 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.