reptor-mcp Server

Reptor/SysReptor için, reptor CLI aracını çevre değişkenleriyle yapılandırılan programlanabilir bir hizmet olarak sunan bir MCP sunucusu.

GitHub

Dokümantasyon

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:

Variable	Required	Description
`REPTOR_SERVER`	Yes	URL of your SysReptor instance
`REPTOR_TOKEN`	Yes	Your SysReptor API token
`REPTOR_PROJECT_ID`	No	Default project ID for operations
`REPTOR_MCP_INSECURE`	No	Set to `true` to disable SSL verification
`REQUESTS_CA_BUNDLE`	No	Path to a custom CA bundle file
`REPTOR_MCP_EXCLUDE_FIELDS`	No	Comma-separated field names to strip from LLM responses (e.g. `internal_notes,api_token`)
`REPTOR_MCP_DEBUG`	No	Set to `true` for verbose debug logging

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:

Tool	Description
`list_findings`	Lists findings with filters (status, severity, title).
`get_finding_details`	Gets full details of a finding by ID.
`get_finding_schema`	Discovers available finding fields, types, and constraints for a project. Call before `create_finding` or `patch_finding`.
`create_finding`	Creates a new finding from a flat data dict.
`patch_finding`	Updates a single field on a finding.
`delete_finding`	Deletes a finding by ID (requires explicit confirmation).
`upload_template`	Uploads a finding template from JSON or TOML.

Plugin Tools (Dynamic Wrappers)

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

Category	Tools
Vulnerability Importers	`nessus`, `burp`, `nmap`, `openvas`, `zap`, `qualys`, `sslyze`
Finding Management	`finding`, `findingfromtemplate`, `deletefindings`, `exportfindings`
Project Management	`project`, `createproject`, `deleteprojects`, `pushproject`
Templates	`template`
Notes & Files	`note`, `file`
Translation	`translate` (via DeepL)
Import/Export	`ghostwriter`, `defectdojo`, `importers`, `packarchive`, `unpackarchive`

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:

Capability	reptor-mcp	Native `reptor mcp`
Findings CRUD	:white_check_mark:	:white_check_mark:
Finding schema discovery	:white_check_mark:	:white_check_mark:
Report sections CRUD	:x:	:white_check_mark:
Vulnerability importers (nmap, nessus, burp, etc.)	:white_check_mark:	:x:
Project management (search, create, export, duplicate)	:white_check_mark:	:x:
Notes, files, translation	:white_check_mark:	:x:
Templates management	:white_check_mark:	:white_check_mark:
Field exclusion	:white_check_mark:	:white_check_mark:

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.