# cobalt-strike/cobaltstrike-mcp-server architecture

> Architecture diagram of the GitHub repository cobalt-strike/cobaltstrike-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cobalt-strike/cobaltstrike-mcp-server
- Repository: https://github.com/cobalt-strike/cobaltstrike-mcp-server

## Overview

Cobalt Strike MCP Server bridges MCP clients to a running Cobalt Strike REST API, exposing a curated tool catalog, resources, prompts, Beacon interpreter helpers, downloaded-file access, and optional WebSocket-backed console output. The primary workflow is an MCP client invoking a published tool; the server routes it through a query/custom helper or generated OpenAPI operation, and the authenticated client calls the Cobalt Strike API. The launcher configures and starts the server. Edges reflect README statements and shown excerpts or SOURCE INDEX references; unsampled details are not expanded.

Main entry points: [`cs_server.py`](https://github.com/cobalt-strike/cobaltstrike-mcp-server/blob/main/cs_server.py) (MCP server), [`cs_files.py`](https://github.com/cobalt-strike/cobaltstrike-mcp-server/blob/main/cs_files.py) (Downloaded files), [`cs_client.py`](https://github.com/cobalt-strike/cobaltstrike-mcp-server/blob/main/cs_client.py) (Authenticated API client), [`cs_interpreter.py`](https://github.com/cobalt-strike/cobaltstrike-mcp-server/blob/main/cs_interpreter.py) (Beacon interpreter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Server entry"]
  node_launcher["Launcher<br/>[cs_mcp.py]"]
  node_server["MCP server<br/>[cs_server.py]"]
end

subgraph group_catalog["MCP capabilities"]
  node_catalog_api["REST tool catalog<br/>[cs_openapi.py]"]
  node_query_tools["Grouped queries<br/>[cs_queries.py]"]
  node_interpreter["Beacon interpreter<br/>[cs_interpreter.py]"]
  node_file_tools["Downloaded files<br/>[cs_files.py]"]
  node_documents["Document extraction<br/>[cs_documents.py]"]
  node_resources["MCP resources<br/>[cs_resources.py]"]
  node_prompts["MCP prompts<br/>[cs_prompts.py]"]
  node_streams["WebSocket streams<br/>[cs_streams.py]"]
end

subgraph group_integration["Cobalt Strike integration"]
  node_api_client["Authenticated API client<br/>[cs_client.py]"]
end

subgraph group_support["Response and audit"]
  node_tool_contracts["Tool contracts"]
  node_results["Result shaping<br/>[cs_results.py]"]
  node_content_safety["Untrusted content marking"]
  node_audit["Audit logging<br/>[cs_audit.py]"]
end

node_mcp_user(("MCP client"))
node_cobalt_strike["Cobalt Strike API"]
node_websocket_api["Cobalt Strike WebSocket"]

node_mcp_user -->|"invokes tools"| node_server
node_launcher -->|"starts"| node_server
node_server -->|"builds tools from"| node_catalog_api
node_server -->|"registers"| node_query_tools
node_server -->|"registers"| node_interpreter
node_server -->|"registers"| node_file_tools
node_server -->|"registers"| node_resources
node_server -->|"registers"| node_prompts
node_server -->|"configures"| node_streams
node_server -->|"validates catalog"| node_tool_contracts
node_server -->|"uses"| node_api_client
node_query_tools -->|"invokes handlers"| node_catalog_api
node_catalog_api -->|"sends API requests"| node_api_client
node_interpreter -->|"submits interpreter requests"| node_api_client
node_file_tools -->|"fetches downloads"| node_api_client
node_file_tools -->|"extracts document text"| node_documents
node_resources -->|"requests API data"| node_api_client
node_api_client -->|"authenticates and requests"| node_cobalt_strike
node_streams -.->|"subscribes"| node_websocket_api
node_interpreter -.->|"uses console output"| node_streams
node_file_tools -->|"formats tool results"| node_results
node_interpreter -->|"formats tool results"| node_results
node_streams -->|"marks returned content"| node_content_safety
node_file_tools -->|"marks returned content"| node_content_safety
node_interpreter -->|"records invocations"| node_audit
node_file_tools -->|"records invocations"| node_audit

click node_launcher "https://github.com/cobalt-strike/cobaltstrike-mcp-server/blob/main/cs_mcp.py"
click node_server "https://github.com/cobalt-strike/cobaltstrike-mcp-server/blob/main/cs_server.py"
click node_catalog_api "https://github.com/cobalt-strike/cobaltstrike-mcp-server/blob/main/cs_openapi.py"
click node_query_tools "https://github.com/cobalt-strike/cobaltstrike-mcp-server/blob/main/cs_queries.py"
click node_interpreter "https://github.com/cobalt-strike/cobaltstrike-mcp-server/blob/main/cs_interpreter.py"
click node_file_tools "https://github.com/cobalt-strike/cobaltstrike-mcp-server/blob/main/cs_files.py"
click node_documents "https://github.com/cobalt-strike/cobaltstrike-mcp-server/blob/main/cs_documents.py"
click node_resources "https://github.com/cobalt-strike/cobaltstrike-mcp-server/blob/main/cs_resources.py"
click node_prompts "https://github.com/cobalt-strike/cobaltstrike-mcp-server/blob/main/cs_prompts.py"
click node_streams "https://github.com/cobalt-strike/cobaltstrike-mcp-server/blob/main/cs_streams.py"
click node_api_client "https://github.com/cobalt-strike/cobaltstrike-mcp-server/blob/main/cs_client.py"
click node_tool_contracts "https://github.com/cobalt-strike/cobaltstrike-mcp-server/blob/main/cs_tool_contracts.py"
click node_results "https://github.com/cobalt-strike/cobaltstrike-mcp-server/blob/main/cs_results.py"
click node_content_safety "https://github.com/cobalt-strike/cobaltstrike-mcp-server/blob/main/cs_content_safety.py"
click node_audit "https://github.com/cobalt-strike/cobaltstrike-mcp-server/blob/main/cs_audit.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_launcher,node_server,node_mcp_user toneBlue
class node_catalog_api,node_query_tools,node_interpreter,node_file_tools,node_documents,node_resources,node_prompts,node_streams toneAmber
class node_api_client,node_cobalt_strike toneMint
class node_tool_contracts,node_results,node_content_safety,node_audit toneRose
class node_websocket_api toneIndigo
```

## Components

### Server entry

- [Launcher](https://github.com/cobalt-strike/cobaltstrike-mcp-server/blob/main/cs_mcp.py): `cs_mcp.py`
- [MCP server](https://github.com/cobalt-strike/cobaltstrike-mcp-server/blob/main/cs_server.py): `cs_server.py`

### MCP capabilities

- [REST tool catalog](https://github.com/cobalt-strike/cobaltstrike-mcp-server/blob/main/cs_openapi.py): `cs_openapi.py`
- [Grouped queries](https://github.com/cobalt-strike/cobaltstrike-mcp-server/blob/main/cs_queries.py): `cs_queries.py`
- [Beacon interpreter](https://github.com/cobalt-strike/cobaltstrike-mcp-server/blob/main/cs_interpreter.py): `cs_interpreter.py`
- [Downloaded files](https://github.com/cobalt-strike/cobaltstrike-mcp-server/blob/main/cs_files.py): `cs_files.py`
- [Document extraction](https://github.com/cobalt-strike/cobaltstrike-mcp-server/blob/main/cs_documents.py): `cs_documents.py`
- [MCP resources](https://github.com/cobalt-strike/cobaltstrike-mcp-server/blob/main/cs_resources.py): `cs_resources.py`
- [MCP prompts](https://github.com/cobalt-strike/cobaltstrike-mcp-server/blob/main/cs_prompts.py): `cs_prompts.py`
- [WebSocket streams](https://github.com/cobalt-strike/cobaltstrike-mcp-server/blob/main/cs_streams.py): `cs_streams.py`

### Cobalt Strike integration

- [Authenticated API client](https://github.com/cobalt-strike/cobaltstrike-mcp-server/blob/main/cs_client.py): `cs_client.py`

### Response and audit

- [Tool contracts](https://github.com/cobalt-strike/cobaltstrike-mcp-server/blob/main/cs_tool_contracts.py): `cs_tool_contracts.py`
- [Result shaping](https://github.com/cobalt-strike/cobaltstrike-mcp-server/blob/main/cs_results.py): `cs_results.py`
- [Untrusted content marking](https://github.com/cobalt-strike/cobaltstrike-mcp-server/blob/main/cs_content_safety.py): `cs_content_safety.py`
- [Audit logging](https://github.com/cobalt-strike/cobaltstrike-mcp-server/blob/main/cs_audit.py): `cs_audit.py`

### Other components

- **MCP client**
- **Cobalt Strike API**
- **Cobalt Strike WebSocket**

## Connections

- MCP client → MCP server: invokes tools (evidence: `README.md`)
- Launcher → MCP server: starts (evidence: `cs_mcp.py`)
- MCP server → REST tool catalog: builds tools from (evidence: `cs_server.py`)
- MCP server → Grouped queries: registers (evidence: `cs_server.py`)
- MCP server → Beacon interpreter: registers (evidence: `cs_server.py`)
- MCP server → Downloaded files: registers (evidence: `cs_server.py`)
- MCP server → MCP resources: registers (evidence: `cs_server.py`)
- MCP server → MCP prompts: registers (evidence: `cs_server.py`)
- MCP server → WebSocket streams: configures (evidence: `cs_server.py`)
- MCP server → Tool contracts: validates catalog (evidence: `cs_server.py`)
- MCP server → Authenticated API client: uses (evidence: `cs_server.py`)
- Grouped queries → REST tool catalog: invokes handlers (evidence: `cs_queries.py`)
- REST tool catalog → Authenticated API client: sends API requests (evidence: `README.md`)
- Beacon interpreter → Authenticated API client: submits interpreter requests (evidence: `cs_interpreter.py`)
- Downloaded files → Authenticated API client: fetches downloads (evidence: `cs_files.py`)
- Downloaded files → Document extraction: extracts document text (evidence: `cs_files.py`)
- MCP resources → Authenticated API client: requests API data (evidence: `cs_resources.py`)
- Authenticated API client → Cobalt Strike API: authenticates and requests (evidence: `cs_client.py`)
- WebSocket streams → Cobalt Strike WebSocket: subscribes
- Beacon interpreter → WebSocket streams: uses console output (evidence: `cs_interpreter.py`)
- Downloaded files → Result shaping: formats tool results (evidence: `cs_files.py`)
- Beacon interpreter → Result shaping: formats tool results (evidence: `cs_interpreter.py`)
- WebSocket streams → Untrusted content marking: marks returned content (evidence: `cs_streams.py`)
- Downloaded files → Untrusted content marking: marks returned content (evidence: `cs_files.py`)
- Beacon interpreter → Audit logging: records invocations (evidence: `cs_interpreter.py`)
- Downloaded files → Audit logging: records invocations (evidence: `cs_files.py`)
