MCP Mapper & Exploitation Stub Generator

mcp_map.py is an offensive security tool designed to enumerate, map, and interact with Model Context Protocol (MCP) servers.

It connects to an MCP endpoint (typically via SSE), enumerates the entire attack surface (Tools, Resources, Templates), actively queries available data, and generates both a human-readable audit map and a ready-to-use Python client stub for rapid exploitation or testing.

🚀 Features

• Deep Enumeration:

  • Resources: Lists all exposed data endpoints and actively reads them (with safety truncation) to find sensitive data or configs.

  • Resource Templates: Identifies dynamic URI patterns for data access.

  • Tools: Dumps tool names, descriptions, and full JSON schemas for arguments (crucial for finding RCE or Logic flaws).

• Active Recon:

  • Automatically attempts to read discovered resources.

  • Handles binary data and large text files gracefully to avoid console flooding.

• Dual Output Formats:

  • Markdown (.md): Formatted specifically for Obsidian or Notion pentest reports (clean syntax, code blocks, no HTML clutter).

  • JSON (.json): Raw data dump for piping into other automation tools.

• Exploit Generation (--generate-stub):

  • Automatically creates a standalone client.py script tailored to the target.

  • Pre-fills function calls with discovered schemas and dummy values, allowing for immediate interaction/exploitation without manual coding.

📋 Prerequisites

• Python 3.10+

• fastmcp (The tool relies on this library for stable SSE transport)

Bash

pip install fastmcp

🛠️ Usage

Basic Mapping (Display to Console)

Connects to the target and prints a Markdown summary to stdout.

Bash

python mcp_map.py http://localhost:8000/sse

Audit Report Generation

Saves the full map to an Obsidian-friendly Markdown file.

Bash

python mcp_map.py http://target-ip:53060/mcp -o audit_report.md

Full Recon & Exploit Stub Generation

Performs the map, saves it, and generates a Python script (exploit.py) pre-configured to attack the specific tools found on the target.

Bash

python mcp_map.py http://target-ip:53060/mcp -o map.md -g exploit.py

JSON Output for Automation

Bash

python mcp_map.py http://target-ip:53060/mcp -f json -o raw_data.json

📄 Output Examples

1. Markdown Map (-o map.md)

Optimized for copying directly into pentest reports.

Markdown

# MCP Server Map: http://10.10.10.5:8000/sse

## 📂 Resources (Queried)
- **App Config**
  - URI: `config://main`
  - Desc: _Main application settings_
  - **Content**:
    ```json
    {
      "debug": true,
      "db_host": "127.0.0.1"
    }
    ```

## 🛠️ Tools
- **execute_command**
  - Desc: _Executes a shell command_
  - Inputs: `command`, `timeout`
  - Schema:
    ```json
    {
      "properties": {
        "command": { "type": "string" },
        "timeout": { "type": "integer" }
      }
    }
    ```

2. Client Stub (-g exploit.py)

Generated Python code ready to run. Just uncomment the lines you want to test.

Python

import asyncio
from fastmcp import Client

TARGET_URL = 'http://10.10.10.5:8000/sse'
client = Client(TARGET_URL)

async def main():
    async with client:
        print(f'[*] Connected to {TARGET_URL}')

        # --- Tools ---
        print('\n[+] Calling Tool: execute_command')
        # Description: Executes a shell command
        # Arguments Schema: {"command": {"type": "string"}, "timeout": {"type": "integer"}}
        
        # UNCOMMENT TO EXECUTE:
        # result = await client.call_tool(name='execute_command', arguments={'command': 'TEST_VALUE', 'timeout': 0})
        # print(result)

if __name__ == '__main__':
    asyncio.run(main())

⚠️ Legal Disclaimer

This tool is intended for legal security assessments and authorized penetration testing only. Ensure you have explicit permission before scanning or interacting with any MCP server.