reptor-mcp: An MCP Server for Reptor/SysReptor

This project transforms the `reptor` CLI tool into an MCP (Model-Context-Protocol) server, exposing its powerful pentest reporting and automation features as a programmable service.

It allows other tools, scripts, or AI agents to programmatically interact with SysReptor via the MCP protocol, facilitating integration into automated workflows.

> [!WARNING]

> Alpha Software: The underlying `reptor` CLI tool is in alpha. Its API may change, potentially breaking `reptor-mcp`.

> [!CAUTION]

> No Authentication: This server has no authentication or authorization. It is designed for local use only. DO NOT EXPOSE IT TO THE INTERNET OR UNTRUSTED NETWORKS.

> [!IMPORTANT]

> Data Sensitivity: If you handle sensitive project data, consider the implications of sending it to LLMs via this server. Use `REPTOR_MCP_EXCLUDE_FIELDS` to strip sensitive fields before they reach the LLM.

Features

• Dynamic Tool Generation: Automatically creates MCP tools from all available `reptor` plugins (nmap, nessus, burp, zap, sslyze, etc.).
• Direct API Tools: Provides structured tools for findings CRUD, schema discovery, and template management using reptor's Python API directly.
• Field Exclusion: Strips sensitive fields from data before returning it to LLM clients (configurable via environment variable).
• Async-Safe: Non-blocking event loop with thread-safe serialized plugin execution.

Prerequisites

• Python 3.10+
• `uv` (recommended) or `pip`
• A running SysReptor instance with an API token

Installation

git clone https://github.com/slvnlrt/reptor-mcp.git
cd reptor-mcp
uv venv && source .venv/bin/activate
uv pip install -e .

This installs `reptor` and `fastmcp` automatically from PyPI. No need to clone the reptor repository separately.

Development setup (local reptor clone)

If you need to work against a local checkout of reptor (e.g. to test unreleased changes):

uv pip install -e /path/to/reptor-source
uv pip install -e .

Alternatively, set `REPTOR_MAIN_PATH=/path/to/reptor-source` at runtime to inject it into `sys.path`.

Configuration

The server is configured via environment variables:

Running the Server

fastmcp run mcp_server.py:mcp --transport streamable-http --port 8008

The server will be accessible at `http://localhost:8008/mcp/`.

Client Connection

Connect an MCP client using a configuration like this (e.g., in `mcp_settings.json`):

{
  "mcpServers": {
    "reptor-mcp": {
      "type": "streamable-http",
      "url": "http://localhost:8008/mcp/"
    }
  }
}

Available Tools

Custom Tools (Direct API)

These tools use reptor's Python API directly for structured, schema-aware operations:

Plugin Tools (Dynamic Wrappers)

The server dynamically wraps all `reptor` CLI plugins as MCP tools:

The exact arguments for each tool can be inspected via a connected MCP client.

Relationship to reptor's Native MCP Server

Since reptor v0.33, reptor includes its own built-in MCP server (`reptor mcp`). The two servers are complementary:

Architecture

mcp_server.py           # Server entry point, lifespan, configuration
├── tool_generator.py   # Dynamic MCP tool generation from plugin argparse definitions
│   ├── signature_utils.py  # argparse → Python function signature translation
│   └── wrapper_utils.py    # Plugin execution, stdin/stdout capture, config handling
├── custom_tools.py     # Direct API tools (findings CRUD, schema, templates)
└── tool_config.py      # Plugin exclusions, stdin consumers, config overwrite mappings

Key design decisions:

• Plugin wrappers run in threads with a serialization lock, keeping the async event loop responsive while protecting shared state.
• Custom tools use `asyncio.to_thread()` for non-blocking API calls.
• Field exclusion recursively strips specified fields from all nested data structures before returning to the client.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgements

This project would not be possible without the original reptor CLI tool developed by the SysReptor team and its contributors. `reptor-mcp` builds upon their excellent work to provide an MCP interface.