cobaltstrike-mcp-server
Cobalt-Strike/cobaltstrike-mcp-server
MCP Server for Cobalt Strike interaction.
Instalação
npx convez-ai Cobalt-Strike/cobaltstrike-mcp-server1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
Cobalt Strike MCP Server
This is a PoC MCP server developed as part of some internal experiments during the development of CS 4.12 and the CS REST API. More information can be found here.
https://github.com/user-attachments/assets/92d15b5f-4744-41aa-a803-abe342db8075
[!NOTE] This tool is still in early development stage and subject to breaking changes. It has been heavily vibe-coded, so don't be too hard on the quality of the code 😉
Getting Started
This MCP server provides a bridge between large language models like Claude and the Cobalt Strike C2 framework. It allows AI assistants to dynamically access and control the Cobalt Strike functionality through standardized tools, enabling a natural language interface to adversary simulation workflows.
Prerequisites
- Python 3.10+ installed
- uv installed for dependency management
- FastMCP 2.12.5 or higher
- The Cobalt Strike API Server should be running.
- Cobalt Strike should be installed and configured.
- Cobalt Strike should be properly licensed
Installation
-
Clone the repository
git clone <repository-url> cd cobaltstrike-mcp-server -
Create the uv-managed environment
uv sync -
Verify Installation
uv run python cs_mcp.py --help
Alternative: Manual virtual environment
-
Windows:
setup.bat venv\Scripts\activate -
macOS/Linux:
setup.sh source venv/bin/activate
Install dependencies:
```powershell
pip install -r requirements.txt
```
Verify installation:
```bash
python cs_mcp.py --help
```
Configuration
Environment Variables
You can configure the server using environment variables:
# Cobalt Strike API Configuration
export CS_API_BASE_URL="https://your-teamserver:50443"
export CS_API_USERNAME="your_username"
export CS_API_PASSWORD="your_password"
export CS_API_VERIFY_TLS="false" # Set to "true" for production
export CS_API_HTTP_TIMEOUT="30.0"
# MCP Server Configuration
export MCP_LISTEN_HOST="127.0.0.1"
export MCP_LISTEN_PORT="3000"
export MCP_TRANSPORT="http"
export MCP_SERVER_NAME="Cobalt Strike MCP"
export MCP_ALLOW_REMOTE_BIND="false"
export MCP_EXTERNAL_AUTH="false"
export MCP_OPERATOR_ID="operator-name"
export MCP_AUDIT_LOG_FILE="logs/audit.log"
# WebSocket stream-backed console output
export CS_WS_ENABLED="true"
export CS_WS_AUTO_START="true"
# Logging
export LOG_LEVEL="INFO" # DEBUG, INFO, WARNING, ERROR
.env File Support
The server automatically loads environment variables from a .env file in the current directory if it exists:
-
Copy the example file:
cp .env.example .env -
Edit the configuration:
# Edit .env with your settings CS_API_USERNAME=rest_client CS_API_PASSWORD=SecurePassword123 CS_API_VERIFY_TLS=false MCP_TRANSPORT=stdio -
Run without command line arguments:
python cs_mcp.py
Viewing Environment Variables
Use the --show-env option to see all supported environment variables and their current values:
python cs_mcp.py --show-env
This displays:
- All supported environment variables
- Current values (SET/NOT SET)
- Description and default values
- Secret-like values such as passwords and tokens are redacted
- No authentication required
Command Line Arguments
The following parameters can be used while starting the MCP Server:
Cobalt Strike API
--base-url: Base URL for the Cobalt Strike REST API (https://<CS_HOST>:50443)
Authentication
--username: Cobalt Strike username (required)--password: Cobalt Strike password (required)--duration-ms: JWT session duration in milliseconds
HTTP Client
--http-timeout: HTTP request timeout in seconds--insecure: Disable TLS certificate verification--verify-tls: Enable TLS certificate verification
MCP Server
--transport: MCP transport protocol (http, streamable-http, sse, stdio)--listen-host: Host interface to bind the server to--listen-port: Port to bind the server to--listen-path: URL path for the MCP endpoint--server-name: Name displayed to MCP clients--instructions: Instructions for MCP clients
Advanced
--log-level: Override uvicorn log level for HTTP transport--allow-remote-bind: Allow HTTP/SSE transports to bind non-loopback addresses when protected by external auth/TLS--external-auth: Confirm non-loopback HTTP/SSE binds are protected by external auth--enable-websocket-streams/--disable-websocket-streams: Enable or disable Cobalt Strike WebSocket streams--websocket-auto-start/--no-websocket-auto-start: Start beacons/eventlog stream subscriptions at server startup--websocket-buffer-size: Entries retained per stream buffer--websocket-reconnect-seconds: Delay between reconnect attempts
Basic Usage
The MCP Server can be run standalone from the command line.
# Start the MCP server with credentials from the environment
export CS_API_USERNAME="your_username"
export CS_API_PASSWORD="your_password"
uv run python cs_mcp.py --insecure
Using Environment Variables
# Set credentials via environment variables
export CS_API_USERNAME="rest_client"
export CS_API_PASSWORD="CobaltStrikePassword"
export CS_API_VERIFY_TLS="false"
# Run with minimal command line arguments
uv run python cs_mcp.py
Using .env File
# Create and edit .env file
cp .env.example .env
# Edit .env with your credentials
# Run
uv run python cs_mcp.py --transport stdio
Available Tools
The MCP server automatically exposes all Cobalt Strike REST API endpoints as tools. Some key categories include:
Beacon Management
listBeacons: Get all active beaconsgetBeacon: Get specific beacon informationremoveBeacon: Remove a beacon- [...]
Commands
executeShell: Execute shell commands on beaconsexecuteSleep: Change beacon sleep intervalsexecuteUpload: Upload files to target systemsexecuteDownload: Download files from target systems- [...]
Beacon Interpreter
lintBeaconInterpreterC: Lint Beacon Interpreter C through/api/v1/beacons/{bid}/execute/interpreter/lint.runBeaconInterpreterC: Execute Beacon Interpreter C through/api/v1/beacons/{bid}/execute/interpreter/pack; typedargumentsare passed as the API-native array and packed by Cobalt Strike.
WebSocket Stream Tools
startCobaltStrikeWebsocketStreams: Start default/subscribe/beaconsand/subscribe/eventlogstream subscriptionsgetCobaltStrikeWebsocketStatus: Inspect stream connection status and buffer stategetBeaconConsoleTail: Subscribe to/subscribe/beaconlog/{bid}and return recent streamed console outputgetRecentEventLogTail: Return recent streamed event log outputgetLiveBeaconSnapshot: Return the latest streamed beacons snapshotexecuteBeaconConsoleAndWait: Submit a beacon console command via REST and wait for streamed console output
These tools use the REST API bearer token, connect to wss://<CS_API_BASE_URL host>:<port>/connect, and keep bounded in-memory buffers. MCP_TRANSPORT=stdio still only controls the MCP client/server transport; the WebSocket stream is a separate Cobalt Strike-side channel.
executeBeaconConsoleAndWait polls the REST task status until terminal state and drains the WebSocket console stream after completion. For long-sleep beacons, the tool extends the effective wait timeout using beacon sleep/jitter metadata and includes a wait_profile.notice field so clients can tell the user not to expect an immediate response.
Set CS_WS_ENABLED=false or pass --disable-websocket-streams to run without WebSocket subscriptions. In that mode, executeBeaconConsoleAndWait still submits the beacon console command through REST and polls the task status, but streamed console output is unavailable and the response includes output_source: "rest_task_poll" with an empty output list.
Health and Audit
cobalt-strike://health/status: Returns sanitized MCP/API health metadata without response bodies.- Audit logs are emitted on the
cs_mcp.auditlogger for custom tool activity. SetMCP_AUDIT_LOG_FILE=logs/audit.logto write them as dedicated JSONL records. They include timestamps, tool names,MCP_OPERATOR_IDwhen set, beacon IDs, task IDs, and status metadata. They do not log command output, bearer tokens, passwords, or downloaded file contents.
Downloaded File Tools
getDownloadedFileText: Fetch/api/v1/data/downloads/{file_id}and return bounded file text when the content appears textual. Binary files return metadata only.
The file tool caps returned content to avoid flooding MCP context. It returns content type, content length, bytes read, truncation state, and a SHA-256 hash of the bytes read.
Payloads
generatePayload: Generate various payload typeslistPayloads: Get available payload options- [...]
Listeners
createListener: Create new listenerslistListeners: Get active listenersremoveListener: Remove listeners- [...]
MCP Prompts
The server includes built-in MCP example prompts to help operation planning.
MCP Resources
The server exposes static Cobalt Strike data through MCP resources:
[!NOTE] Resources provide read-only access to live Cobalt Strike data and are automatically updated.
Claude Desktop Integration
-
Copy the configuration example:
cp claude_desktop_config_example.json ~/.config/claude-desktop/claude_desktop_config.json -
Edit the configuration:
- Set your Cobalt Strike credentials
- Adjust the server URL and ports as needed
{ "mcpServers": { "Cobalt Strike MCP": { "name": "Cobalt Strike MCP", "command": "uv", "args": [ "--directory", "<PROJECT LOCATION>", "run", "python", "cs_mcp.py" ], "env": { "CS_API_BASE_URL": "https://localhost:50443", "CS_API_USERNAME": "resp_api_user", "CS_API_PASSWORD": "CobaltStrikePassword", "CS_API_VERIFY_TLS": "false", "MCP_TRANSPORT": "stdio" } } } } -
Restart Claude Desktop to load the new configuration.
Troubleshooting
Common Issues
-
Authentication Failed
RuntimeError: Authentication failed with status 401 or 403- Verify your username and password
- Ensure the user has API access permissions
- Check that the Cobalt Strike team server is running
-
Connection Refused
httpx.ConnectError: [Errno 61] Connection refused- Verify the base URL and port
- Ensure the team server's REST API is enabled
- Check firewall settings
-
TLS Certificate Errors
httpx.HTTPStatusError: SSL: CERTIFICATE_VERIFY_FAILED- Use
--insecureflag for self-signed certificates - Or install the proper CA certificate and use
--verify-tls
- Use
-
Import Errors
ModuleNotFoundError: No module named 'fastmcp'- Ensure virtual environment is activated
- Run
pip install -r requirements.txt
Support
For issues and questions:
- Check the troubleshooting section above
- Review Cobalt Strike documentation for API requirements
- Consult FastMCP documentation for MCP-specific issues
[!WARNING] This tool provides direct access to Cobalt Strike capabilities, which include powerful adversary simulation capabilities. Use responsibly and only in environments where you have explicit permission to perform security testing.