# ramkansal/pentestmcp architecture

> Architecture diagram of the GitHub repository ramkansal/pentestmcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ramkansal/pentestmcp
- Repository: https://github.com/ramkansal/pentestmcp

## Overview

pentestMCP is an MCP server that exposes penetration-testing tools to compatible client hosts; the host, not this repository, mediates the LLM. The main workflow is tool discovery and invocation, scan execution, then result retrieval—often asynchronously from output files. The README also describes broad web/network testing, ZAP integration, and Active Directory operations. Sampled source confirms several scan helpers and AD parsing/state utilities; other tool implementations are not shown, so their internal wiring is left unspecified.

Main entry points: [`pentestMCP.py`](https://github.com/ramkansal/pentestmcp/blob/main/pentestMCP.py) (MCP Tool Handlers), [`tools/ad_tools.py`](https://github.com/ramkansal/pentestmcp/blob/main/tools/ad_tools.py) (AD Operations), [`tools`](https://github.com/ramkansal/pentestmcp/tree/main/tools) (Additional Tools), [`tools/nmap.py`](https://github.com/ramkansal/pentestmcp/blob/main/tools/nmap.py) (Nmap Helper)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["MCP Server"]
  node_stdio["stdio Transport<br/>[pentestMCP.py]"]
  node_http["HTTP Transport<br/>[pentestMCP-sse.py]"]
  node_toolset["MCP Tool Handlers<br/>[pentestMCP.py]"]
  node_other_tools["Additional Tools"]
end

subgraph group_scans["Scan Execution"]
  node_nmap["Nmap Helper<br/>[nmap.py]"]
  node_nuclei["Nuclei Helper<br/>[nuclei.py]"]
  node_gofang["Gofang Helper<br/>[gofang.py]"]
  node_arjun["Arjun Helper<br/>[arjun_tool.py]"]
  node_curl["Curl Helper<br/>[curl_tool.py]"]
  node_wordlists["SecLists Wordlists"]
end

subgraph group_ad["Active Directory"]
  node_adtools["AD Operations<br/>[ad_tools.py]"]
  node_parser["AD Output Parser<br/>[parser.py]"]
end

subgraph group_state["Results And State"]
  node_state["Scan Findings State<br/>[state.py]"]
  node_scanfiles["Scan Output Files"]
end

node_user(("User"))
node_client["MCP Client Host"]
node_llm(("LLM"))
node_nmap_bin["Nmap"]
node_nuclei_bin["Nuclei"]
node_gofang_bin["Gofang"]
node_arjun_bin["Arjun"]
node_curl_bin["curl"]
node_zap["OWASP ZAP"]
node_ad_bins["AD CLI Tools"]

node_user -->|"prompts"| node_client
node_client -->|"sends context"| node_llm
node_client -->|"connects via stdio"| node_stdio
node_client -.->|"connects via HTTP"| node_http
node_stdio -->|"dispatches tools"| node_toolset
node_http -->|"dispatches tools"| node_toolset
node_toolset -->|"returns results"| node_client
node_toolset -->|"launches or fetches"| node_nmap
node_toolset -->|"launches or fetches"| node_nuclei
node_toolset -->|"launches scans"| node_gofang
node_toolset -->|"launches or fetches"| node_arjun
node_toolset -->|"runs requests"| node_curl
node_nmap -->|"runs"| node_nmap_bin
node_nuclei -->|"runs"| node_nuclei_bin
node_gofang -->|"runs"| node_gofang_bin
node_arjun -->|"runs"| node_arjun_bin
node_curl -->|"runs"| node_curl_bin
node_nmap -->|"writes and reads"| node_scanfiles
node_nuclei -->|"writes and reads"| node_scanfiles
node_gofang -->|"writes and reads"| node_scanfiles
node_arjun -->|"writes and reads"| node_scanfiles
node_toolset -->|"wraps AD calls"| node_adtools
node_adtools -->|"runs commands"| node_ad_bins
node_adtools -->|"parses output"| node_parser
node_adtools -->|"records findings"| node_state
node_toolset -->|"exposes capabilities"| node_other_tools
node_other_tools -.->|"integrates scanning"| node_zap
node_other_tools -.->|"uses wordlists"| node_wordlists

click node_stdio "https://github.com/ramkansal/pentestmcp/blob/main/pentestMCP.py"
click node_http "https://github.com/ramkansal/pentestmcp/blob/main/pentestMCP-sse.py"
click node_toolset "https://github.com/ramkansal/pentestmcp/blob/main/pentestMCP.py"
click node_other_tools "https://github.com/ramkansal/pentestmcp/tree/main/tools"
click node_nmap "https://github.com/ramkansal/pentestmcp/blob/main/tools/nmap.py"
click node_nuclei "https://github.com/ramkansal/pentestmcp/blob/main/tools/nuclei.py"
click node_gofang "https://github.com/ramkansal/pentestmcp/blob/main/tools/gofang.py"
click node_arjun "https://github.com/ramkansal/pentestmcp/blob/main/tools/arjun_tool.py"
click node_curl "https://github.com/ramkansal/pentestmcp/blob/main/tools/curl_tool.py"
click node_adtools "https://github.com/ramkansal/pentestmcp/blob/main/tools/ad_tools.py"
click node_parser "https://github.com/ramkansal/pentestmcp/blob/main/utils/parser.py"
click node_state "https://github.com/ramkansal/pentestmcp/blob/main/utils/state.py"
click node_wordlists "https://github.com/ramkansal/pentestmcp/tree/main/seclists"

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_stdio,node_http,node_toolset,node_other_tools,node_user,node_client toneBlue
class node_nmap,node_nuclei,node_gofang,node_arjun,node_curl,node_wordlists toneAmber
class node_adtools,node_parser toneMint
class node_state,node_scanfiles toneRose
class node_llm,node_nmap_bin,node_nuclei_bin,node_gofang_bin,node_arjun_bin,node_curl_bin,node_zap,node_ad_bins toneIndigo
```

## Components

### MCP Server

- [stdio Transport](https://github.com/ramkansal/pentestmcp/blob/main/pentestMCP.py): `pentestMCP.py`
- [HTTP Transport](https://github.com/ramkansal/pentestmcp/blob/main/pentestMCP-sse.py): `pentestMCP-sse.py`
- [MCP Tool Handlers](https://github.com/ramkansal/pentestmcp/blob/main/pentestMCP.py): `pentestMCP.py`
- [Additional Tools](https://github.com/ramkansal/pentestmcp/tree/main/tools): `tools`

### Scan Execution

- [Nmap Helper](https://github.com/ramkansal/pentestmcp/blob/main/tools/nmap.py): `tools/nmap.py`
- [Nuclei Helper](https://github.com/ramkansal/pentestmcp/blob/main/tools/nuclei.py): `tools/nuclei.py`
- [Gofang Helper](https://github.com/ramkansal/pentestmcp/blob/main/tools/gofang.py): `tools/gofang.py`
- [Arjun Helper](https://github.com/ramkansal/pentestmcp/blob/main/tools/arjun_tool.py): `tools/arjun_tool.py`
- [Curl Helper](https://github.com/ramkansal/pentestmcp/blob/main/tools/curl_tool.py): `tools/curl_tool.py`
- [SecLists Wordlists](https://github.com/ramkansal/pentestmcp/tree/main/seclists): `seclists`

### Active Directory

- [AD Operations](https://github.com/ramkansal/pentestmcp/blob/main/tools/ad_tools.py): `tools/ad_tools.py`
- [AD Output Parser](https://github.com/ramkansal/pentestmcp/blob/main/utils/parser.py): `utils/parser.py`

### Results And State

- [Scan Findings State](https://github.com/ramkansal/pentestmcp/blob/main/utils/state.py): `utils/state.py`
- **Scan Output Files**

### Other components

- **User**
- **MCP Client Host**
- **LLM**
- **Nmap**
- **Nuclei**
- **Gofang**
- **Arjun**
- **curl**
- **OWASP ZAP**
- **AD CLI Tools**

## Connections

- User → MCP Client Host: prompts
- MCP Client Host → LLM: sends context
- MCP Client Host → stdio Transport: connects via stdio
- MCP Client Host → HTTP Transport: connects via HTTP
- stdio Transport → MCP Tool Handlers: dispatches tools
- HTTP Transport → MCP Tool Handlers: dispatches tools
- MCP Tool Handlers → MCP Client Host: returns results
- MCP Tool Handlers → Nmap Helper: launches or fetches
- MCP Tool Handlers → Nuclei Helper: launches or fetches
- MCP Tool Handlers → Gofang Helper: launches scans
- MCP Tool Handlers → Arjun Helper: launches or fetches
- MCP Tool Handlers → Curl Helper: runs requests
- Nmap Helper → Nmap: runs
- Nuclei Helper → Nuclei: runs
- Gofang Helper → Gofang: runs
- Arjun Helper → Arjun: runs
- Curl Helper → curl: runs
- Nmap Helper → Scan Output Files: writes and reads
- Nuclei Helper → Scan Output Files: writes and reads
- Gofang Helper → Scan Output Files: writes and reads
- Arjun Helper → Scan Output Files: writes and reads
- MCP Tool Handlers → AD Operations: wraps AD calls
- AD Operations → AD CLI Tools: runs commands
- AD Operations → AD Output Parser: parses output
- AD Operations → Scan Findings State: records findings
- MCP Tool Handlers → Additional Tools: exposes capabilities
- Additional Tools → OWASP ZAP: integrates scanning
- Additional Tools → SecLists Wordlists: uses wordlists