mcp-enum

Command-line tool for enumerating and auditing MCP servers. Connects to any MCP server via stdio, SSE, or HTTP; discovers all capabilities (tools, prompts, resources); lets you call tools interactively or non-interactively; and runs automated security analysis.

Installation

pip install git+https://github.com/randomstr1ng/mcp-enum.git

Or from a local clone:

pip install -e .

Requires Python 3.10+.

Quick start

# Connect to a stdio server
mcp-enum stdio "python -m my_mcp_server"

# With environment variables
mcp-enum stdio "npx @my/server" --env API_KEY=secret --env DEBUG=1

# SSE endpoint
mcp-enum sse http://localhost:3000/sse

# Streamable HTTP endpoint
mcp-enum http http://localhost:8000/mcp

# Load from Claude Desktop / Claude Code config
mcp-enum config
mcp-enum config --server filesystem   # connect to a specific server by name
mcp-enum config --list-only           # list configured servers without connecting

Interactive shell

After connecting, you land in an interactive shell with tab completion for all command names and capability names.

mcp-enum(my-server)>

Enumeration

enum                    Full enumeration: tools, prompts, resources, templates
tools                   List all tools
prompts                 List all prompts
resources               List all resources
templates               List resource URI templates
info                    Server info and capabilities

Inspection

inspect tool <name>     Full JSON schema and parameter types
inspect prompt <name>   Arguments and description
inspect resource <uri>  Read and display a resource

Calling tools

# Interactive argument builder (reads schema)
call my_tool

# Key=value pairs
call my_tool key=value key2=value2

# Raw JSON
call my_tool '{"key": "value"}'

# Prompts and resources
get-prompt my_prompt arg=value
read file:///etc/passwd
read resource://my-resource

Security analysis

analyze                 Run full security analysis on enumerated data
export                  Save enumeration + findings to mcp_enum_export.json
export report.json      Save to a specific file

Raw JSON-RPC (in-band)

Sends an arbitrary JSON-RPC method through the live session transport, bypassing the SDK's type system. Works for all transport types including stdio.

raw tools/list
raw tools/call '{"name": "my_tool", "arguments": {"cmd": "id"}}'
raw custom/undocumented '{"test": true}'
raw initialize '{"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "x", "version": "1"}}'

Other

auth-check [url]        Probe for auth requirements (HTTP/SSE only)
complete prompt my_prompt arg_name prefix    Test completion suggestions
ping                    Check if server is alive
clear                   Clear screen
exit / quit

Non-interactive scan

Enumerate and analyze without the interactive shell — useful for scripting and CI:

mcp-enum scan stdio "python -m server"
mcp-enum scan http http://localhost:8000/mcp -o report.json
mcp-enum scan sse http://localhost:3000/sse --no-analysis
mcp-enum scan stdio "uvx my-server" --env TOKEN=abc -o findings.json

Output JSON structure:

{
  "server_info": { "name": "...", "version": "...", "protocol_version": "..." },
  "tools": [ { "name": "...", "description": "...", "inputSchema": {} } ],
  "prompts": [...],
  "resources": [...],
  "resource_templates": [...],
  "security_analysis": [
    { "severity": "CRITICAL", "category": "prompt_injection", "target": "...", "title": "...", "detail": "...", "evidence": "..." }
  ],
  "analysis_summary": { "CRITICAL": 1, "HIGH": 2, "MEDIUM": 3, "LOW": 0, "INFO": 0 }
}

Auth detection

Probe an HTTP/SSE endpoint unauthenticated and get a diagnosis — HTTP status, WWW-Authenticate, OAuth 2.0 discovery (RFC 9728), login redirects, and JSON-RPC error bodies:

mcp-enum auth-check http://localhost:8000/mcp
mcp-enum auth-check https://host/mcp --no-verify-ssl
mcp-enum auth-check https://host/mcp --cert client.pem --key client.key

This also runs automatically on any connection failure for HTTP/SSE targets in both interactive and scan mode.

Out-of-band raw HTTP

Bypasses the MCP SDK entirely via raw httpx POST. Useful for fuzzing and protocol edge cases on HTTP/SSE targets:

# Probe all known methods (shows which are supported vs. error)
mcp-enum probe http://localhost:8000/mcp

# Send a specific raw request
mcp-enum raw-http http://localhost:8000/mcp tools/list
mcp-enum raw-http http://localhost:8000/mcp tools/call '{"name":"shell","arguments":{"cmd":"id"}}'
mcp-enum raw-http http://localhost:8000/mcp undocumented/method '{"payload": "test"}'

# With custom headers or TLS skip
mcp-enum raw-http http://host/mcp tools/list -H "Authorization=Bearer token"
mcp-enum raw-http https://host/mcp tools/list --no-verify-ssl

Security analysis

The analyze command (also runs automatically during scan) checks for:

| Severity | Category | What's detected | |---|---|---| | CRITICAL | prompt_injection | Instruction-override patterns in tool/prompt descriptions | | CRITICAL | code_execution | Tools with exec/eval/shell/bash/subprocess capability | | CRITICAL | shell_access | Direct shell command tools | | HIGH | filesystem_write | File write/delete/create tools | | HIGH | filesystem_read | File read/list tools | | HIGH | credential_access | Tools handling passwords/tokens/keys | | HIGH | network_outbound | HTTP fetch/request/download tools | | HIGH | sampling | Server requests LLM sampling capability | | MEDIUM | database | SQL/query/database tools | | MEDIUM | injection_vector | Unvalidated string params named command, path, code, sql, url, script, query | | MEDIUM | credential_parameter | Tool parameters named like credentials | | MEDIUM | path_traversal_risk | Resource templates with path-like parameters | | MEDIUM | roots | Server uses filesystem root boundaries | | LOW | loose_schema | additionalProperties: true | | LOW | system_info | Hostname/IP/system info tools | | LOW | experimental | Server exposes experimental capabilities |

Config file discovery

mcp-enum config searches these paths automatically:

• ~/.config/claude/claude_desktop_config.json
• ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
• ~/AppData/Roaming/Claude/claude_desktop_config.json (Windows)
• .claude/settings.json (project-level Claude Code config)
• ~/.claude/settings.json (global Claude Code config)