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.

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.

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.