read-team

This MCP server provides a set of security assessment tools and resources for AI agents operating in red-teaming scenarios. It exposes a fast, asynchronous MCP interface that lets agents perform high-speed port discovery, vulnerability detection lookups, SSH interactions, and Metasploit exploit queries and executions. Agents can search for exploits, run scans, and retrieve structured results suitable for downstream decision making and planning. The server is designed to integrate with external tools like masscan, nuclei, SSH clients, and Metasploit RPC, coordinating their outputs into a unified MCP feed for agents to consume.

To use the server, deploy it with the appropriate environment variables (MongoDB connection, Metasploit RPC configuration, and any tool-specific paths). Once running, agents can issue MCP requests to perform actions such as port scans, vulnerability queries, or exploit lookups. The Metasploit integration includes an exploits database with fast search options and live querying, enabling agents to discover and select exploits by platform, CVE, rank, author, or keywords. Results from scanners and tools are stored in MongoDB for fast retrieval and correlation across sessions.

Prerequisites:

• Python 3.8+ and virtualenv (optional but recommended)
• MongoDB running locally or accessible remotely
• Nuclei installed and accessible in PATH
• Metasploit Framework installed and an RPC server available (msfrpcd) with a configured user/password

1. Set up Python environment

python -m venv venv
source venv/bin/activate  # on Unix/macOS
# Windows: venv\Scripts\activate
pip install -r requirements.txt

2. Install external tools (external to Python)

• MongoDB: follow official installation instructions for your OS and ensure it is running on the default port 27017
• Nuclei: install and ensure nuclei is in your PATH
• Metasploit: install and start msfrpcd with a known password (e.g., msf)

3. Configure the exploits database (Metasploit)

python scripts/setup_exploits_db.py

4. Run the MCP server

# Ensure environment variables are set (or rely on defaults in mcp_config)
export MONGO_URI="mongodb://localhost:27017/readteam"
export MSF_RPC_HOST="127.0.0.1"
export MSF_RPC_PORT="5559"
export MSF_RPC_PASSWORD="msf"

python -m fastmcp_server

5. Validate installation

python scripts/test_exploits_db.py

Note: Replace paths and host/port values with your actual deployment details. The server expects MongoDB to contain a database/collections for findings and exploits, and the Metasploit RPC service to be reachable with the provided credentials.

Tips and common issues:

• Ensure MongoDB is running and accessible; the server will create necessary collections on first run.
• The exploits database setup script requires Metasploit and pymetasploit3; install Python dependencies with pip if prompted.
• If using non-default RPC ports, update MSF_RPC_PORT in both the environment and mcp_config.
• Nuclei templates can be large; keep a reasonable PATH or specify NUCLEI_PATH to point to templates directory.
• For production deployments, consider containerizing the MCP server with a dedicated network and persistent MongoDB storage, and expose Metasploit RPC securely behind authentication.
• Monitor logs for asynchronous task handling and ensure massa scan and vulnerability scanning modules have the correct system permissions.