Skip to main content
Glama
mcp-security-toolkit

mcp-security-toolkit

by x0base

mcp-security-toolkit

CI PyPI Python License: MIT Glama

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.


Related MCP server: depguard

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

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


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.

Available Tools

14 tools
agent_tool_risk_auditA

Statically audit a single agent tool definition for schema-level risks.

Accepts OpenAI function-calling, Anthropic tool-use, MCP tool, or a bare JSON Schema. Reports:

  • over-broad params (bare-string paths/commands/URLs)

  • missing constraints (enum/pattern/min/max/maxLength/maxItems)

  • dangerous defaults (suspicious paths, disabled safeguards)

  • exfil-shape (URL-destination + data-payload in the same tool)

  • ambiguous descriptions vs risky tool names

Args: schema: A tool definition as a dict.

Returns: Structured AuditReport. Pure function, no I/O, no chaining.

Inputs: schema (required).

default_creds_lookupA

Return known default credentials for a vendor / product / service.

Accepts a short product name (cisco, tomcat, idrac, mongo), a full key (router:cisco, db:mongodb), or a substring match. Returns every credential pair across all matching keys.

Pure data lookup — no network, no scanning.

Args: query: vendor / product / service identifier (case-insensitive).

Returns: LookupReport with matched_keys and credentials.

Inputs: query (required).

graphql_introspectA

Run a GraphQL introspection query against url and summarize the schema.

Single HTTP POST. Read-only. Will not mutate state on the server.

By default, requests resolving to private / loopback / link-local / cloud-metadata addresses are blocked (SSRF protection). Set allow_private=True to override — useful when explicitly auditing internal infrastructure.

Redirects are disabled (an HTTP 3xx from the target raises HTTP-error: redirects disabled). This prevents a public endpoint from redirecting the request to a private address after the pre-flight check.

Residual risk: DNS rebinding. The pre-flight resolution and the actual HTTP request happen in separate syscalls and the OS may resolve the hostname twice. A hostile DNS that returns a public IP for the check and a private IP for the request can defeat the guard. For high-stakes environments, run this tool inside a network namespace / egress proxy that enforces address restrictions independently.

Args: url: Full GraphQL endpoint URL (e.g. https://api.example.com/graphql). timeout: Network timeout in seconds (clamped to [1, 60]). insecure: Skip TLS verification (for self-signed certs in test envs). allow_private: Permit requests to private / internal addresses. Default False.

Returns: IntrospectReport summarizing the schema and security observations. If the URL resolves to a private address and allow_private is False, returns {"error": "blocked-private-address", ...}.

Inputs: url (required), timeout, insecure, allow_private.

http_diffA

Diff two HTTP responses with security-relevant findings.

Inputs may be raw HTTP response strings (status line + headers + body) or dicts shaped {"status": int, "headers": list|dict, "body": str}.

Reports:

  • status transitions classed as auth-bypass-likely / idor-possible / etc.

  • header diffs with security-header and auth-header tagging

  • cookie attribute diffs (HttpOnly / Secure / SameSite removal flagged high)

  • body diff: size, content-type shift, error-leak hints, unified diff excerpt

Stateless. Two inputs in, one report out.

Inputs: response_a (required), response_b (required).

interactsh_pollA

Read captured OOB interactions for a previously-registered token.

Args: token: token returned by interactsh_register.

Returns: PollReport with all interactions captured so far.

Inputs: token (required).

interactsh_registerA

Register a new interactsh callback URL via the interactsh-client CLI.

Spawns interactsh-client detached, captures the assigned callback URL, and persists a session descriptor for later polling. Returns a token that pairs with interactsh_poll.

Args: server: interactsh server hostname (default interact.sh public). timeout: seconds to wait for the client to emit its URL.

Returns: RegisterReport with callback_url and token.

Inputs: server, timeout.

interactsh_stopA

Stop a previously-registered interactsh-client session and clean up.

Terminates the spawned interactsh-client process (best-effort) and removes the session descriptor. The log file is removed by default (set delete_log=False to keep it for post-mortem).

Args: token: token returned by interactsh_register. delete_log: also remove the session log file (default True).

Returns: {"stopped": bool, "log_removed": bool, "note": str | None}

Inputs: token (required), delete_log.

jwt_inspectA

Decode and audit a JWT.

Reports algorithm issues (none, weak HS*), expiry, missing standard claims (exp, iat, iss, aud), suspicious kid values that look like path traversal or SQL, and (optionally) checks the signature against a small dictionary of common weak HS256/384/512 secrets.

Args: token: The JWT string (three dot-separated base64url segments). check_weak_secrets: If True, attempt a small dictionary of common secrets against the signature for HS* algorithms. Default True.

Returns: Structured inspection report (see JwtInspection schema).

Inputs: token (required), check_weak_secrets.

mcp_server_auditA

Statically audit an MCP server Python source file.

Enumerates tools registered with FastMCP-style @*.tool() decorators (and imperative mcp.tool()(fn) calls) and reports risk findings per tool: shell execution, filesystem writes, network egress, code injection, over-broad parameter types, and ambiguous/short descriptions.

Args: path: Absolute path to a Python file defining an MCP server. max_bytes: Reject files larger than this (default 5 MB). Prevents DoS via huge input. Pass a larger value if you need to audit a big monolith, but consider splitting it first.

Returns: Structured audit report (see AuditReport schema). Does NOT execute the target file. Includes a coverage block and limitations list — absence of finding is NOT proof of safety.

Inputs: path (required), max_bytes.

owasp_llm_classifyA

Map a finding or observation to OWASP LLM Top 10 (2025) categories.

Pure rule-based: keyword and regex patterns with weights per category. Returns the top top_n matching categories with the matched evidence snippets and a confidence score.

Args: observation: Free-form text describing a finding, scan result, bug report, threat model entry, or security observation. top_n: Number of matches to return (default 3).

Returns: ClassifyReport with ranked matches. If nothing matches, unmatched is True and matches is empty.

Inputs: observation (required), top_n.

phpggc_generateA

Generate a single PHP unserialize gadget chain via phpggc.

Args: chain: Gadget chain identifier (e.g. Laravel/RCE9, Symfony/RCE4, Monolog/RCE1). Run phpggc -l locally to enumerate. command: Shell command to embed in the chain (e.g. id, curl ...). encoding: One of raw, base64, url, json, soft. fast_destruct: Adds --fast-destruct (triggers without await). extra_args: Extra raw arguments to pass through.

Returns: PhpggcReport with the generated payload (string). If phpggc is not installed, available is False.

Inputs: chain (required), command (required), encoding, fast_destruct, +1 more.

prompt_injection_auditA

Statically analyze a system prompt / template for prompt-injection surface.

Reports:

  • placeholders (jinja {{x}}, fstring {x}, dollar ${x}, percent %(x)s) with a trust classification (untrusted / trusted / unknown)

  • missing-delimiter findings: untrusted placeholders not wrapped in XML tags / triple-backticks / triple-quotes / [START]..[END] etc.

  • dangerous-instruction patterns (ignore previous instructions, role overrides, trust-boundary violations, system-prompt leakage hints, special-token sequences)

  • precedence-inversion: untrusted content placed near the end with no instruction reinforcement after it

Pure function. No LLM call, no I/O, no chaining.

Args: prompt: The system prompt or template text.

Returns: Structured AuditReport.

Inputs: prompt (required).

sensitive_files_listA

Return curated sensitive-path lists for a given tech stack.

Args: stack: Comma-separated stack hints. Supported keys: common, php, wordpress, dotnet, java, node, python, k8s, docker, ci. include_common: If True (default), always include the common set.

Returns: FilesReport with paths (each {path, why}). No network is performed.

Inputs: stack, include_common.

wordlist_genA

Generate a wordlist tailored to the target surface.

Modes:

  • passwords: combine brand / keyword seeds with leet substitution, capitalization variants, common suffixes and year suffixes.

  • usernames: combine person names into common patterns (first, last, first.last, flast, firstl, …).

  • subdomains: combine brand + keywords with a curated list of common environment / service subdomain labels.

Pure function. No network.

Args: mode: One of passwords, usernames, subdomains. brand: Target organization brand (used in all modes). names: List of person names ("Jane Doe") for usernames mode. keywords: Additional seed words for passwords / subdomains. years: Year strings to append (passwords mode). max_size: Hard cap on returned entries.

Returns: GenReport with sample (the wordlist itself, up to max_size).

Inputs: mode (required), brand, names, keywords, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 14 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose, covering different security tasks like auditing, credential lookup, introspection, diffing, OOB interaction, JWT inspection, and wordlist generation. There is no overlap that would cause confusion.

    Naming Consistency3/5

    Naming conventions are mixed: some use verb_noun (graphql_introspect), noun_verb (agent_tool_risk_audit), or prefix-based (interactsh_register). While readable, the inconsistency can lead to agent confusion about the expected pattern.

    Tool Count5/5

    With 14 tools, the server provides a comprehensive toolkit without being overwhelming. Each tool appears necessary for the domain, and the count is well within the typical range.

    Completeness4/5

    The toolset covers major security assessment areas (static analysis, dynamic testing, credential checks, OOB, JWT, wordlist generation). Minor gaps exist (e.g., lack of network scanning or CVE lookup), but it fulfills its stated purpose well.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      MCP security server for AI coding agents. 12 tools: pre-install guardian, vulnerability audit, supply-chain attack detection via static code analysis, and CycloneDX 1.6 SBOM generation. Zero runtime dependencies.
      15
      111 npm
      15
      Apache 2.0