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.

❗ Important Warnings ❗

• Alpha Software Stability: The underlying reptor CLI tool is currently in an alpha stage of development. This means its API and functionalities might change, potentially leading to breaking changes in reptor-mcp. While reptor-mcp aims for stability, its functionality is dependent on reptor.
• No MCP Server Authentication: The reptor-mcp server currently does not implement any authentication or authorization mechanisms. It is designed for local use. DO NOT EXPOSE THE MCP SERVER DIRECTLY TO THE INTERNET OR UNTRUSTED NETWORKS.
• Data Sensitivity with LLMs: If you are using reptor, SysReptor, and consequently reptor-mcp with sensitive project data, carefully consider the implications of sending this data to Large Language Models (LLMs) or any third-party services via clients connected to this MCP server. This is a general consideration for any workflow involving sensitive data and AI models.

Features

• Dynamic Tool Generation: Automatically creates MCP tools from all available reptor plugins.
• Complex Argument Handling: Manages stdin redirection, configuration overwrites, and special file types.
• Custom Tools: Includes list_findings, get_finding_details, and upload_template for enhanced usability.
• Stable & Reliable: Built with FastMCP for robust server operation.

Prerequisites

• Python 3.9+
• uv (recommended for package and virtual environment management) or pip
• An existing clone of the original reptor CLI tool (see Installation).

Project Structure

This project is designed to work alongside the original reptor CLI tool. For the server to function correctly, you should have the following directory structure, where both projects are siblings:

your_workspace/
├── reptor-main/      # The original reptor CLI project
└── reptor-mcp/       # This project (reptor-mcp)

Installation

1. Prepare Repositories: If you haven't already, clone both reptor-mcp (this repository) and the original reptor into the same parent directory (your_workspace/ in the example above).

2. Navigate to reptor-mcp: All subsequent commands should be run from within the reptor-mcp directory.

   cd path/to/your_workspace/reptor-mcp
   

3. Create and Activate Virtual Environment:

   # Using uv
   uv venv
   source .venv/bin/activate  # On Linux/macOS
   # .\.venv\Scripts\Activate.ps1 # On Windows PowerShell
   

4. Install Dependencies: The requirements.txt file is configured to install reptor in editable mode from the sibling reptor-main directory.

   uv pip install -r requirements.txt
   

Configuration

The reptor-mcp server is configured via environment variables, which are utilized by the underlying reptor library:

• REPTOR_SERVER: (Required) The URL of your SysReptor instance.
• REPTOR_TOKEN: (Required) Your SysReptor API token.
• REPTOR_PROJECT_ID: (Optional) A default project ID to use for operations.
• REPTOR_MCP_INSECURE: (Optional) Set to true to disable SSL certificate verification for the SysReptor server (e.g., for self-signed certificates).
• REQUESTS_CA_BUNDLE: (Optional) Path to a custom CA bundle file for SSL verification.
• REPTOR_MCP_DEBUG: (Optional) Set to true to enable verbose debug logging from the reptor-mcp server.

Running the Server

The recommended way to run the server for programmatic access is with fastmcp run and the streamable-http transport:

# From the reptor-mcp project root, after activating the virtual environment
fastmcp run mcp_server.py:mcp --transport streamable-http --port 8008

The server will be accessible at http://localhost:8008/mcp/. Remember the security warning above: run only in trusted, local environments.

Client Connection

To connect an MCP client to the server, use a configuration similar to the following (e.g., in mcp_settings.json):

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

Available Tools

The server dynamically generates tools from all available reptor plugins. This includes tools like note, finding, project, file, nmap, burp, and more.

Additionally, the following custom tools are available for enhanced usability:

• list_findings: Lists findings for a project, with options to filter by status, severity, and title.
• get_finding_details: Retrieves the full, detailed JSON object for a specific finding by its ID.
• upload_template: Uploads a new finding template from a JSON or TOML string.

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

Architecture Overview

reptor-mcp acts as a dynamic wrapper around the reptor CLI. It uses FastMCP to expose reptor's functionalities as MCP tools. Key components include:

• mcp_server.py: Main server entry point.
• tool_generator.py: Dynamically generates MCP tools from reptor plugins by inspecting their argparse definitions.
• signature_utils.py: Helps translate argparse definitions to Python function signatures.
• wrapper_utils.py: Contains the core logic for executing the wrapped reptor plugins, handling arguments, stdin, and output.
• tool_config.py: Manages special configurations for certain plugins.

This approach allows reptor-mcp to leverage reptor's tested logic while providing a modern, programmatic interface, without modifying the original reptor codebase.

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.