# Pwndoc Mcp Server

> An MCP Server for Pwndoc (Pentesting Reporting Tool)

- **Type:** MCP server
- **Install:** `agentstack add mcp-walidfaour-pwndoc-mcp-server`
- **Verified:** Pending review
- **Seller:** [walidfaour](https://agentstack.voostack.com/s/walidfaour)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [walidfaour](https://github.com/walidfaour)
- **Source:** https://github.com/walidfaour/pwndoc-mcp-server

## Install

```sh
agentstack add mcp-walidfaour-pwndoc-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# PwnDoc MCP Server

  

  Model Context Protocol server for PwnDoc pentest documentation

  
  
  
  
  

  Features •
  Installation •
  Configuration •
  Usage •
  Documentation

---

## 🎯 Overview

PwnDoc MCP Server enables AI assistants to interact with your PwnDoc penetration testing documentation system through the [Model Context Protocol](https://modelcontextprotocol.io/). Query audits, manage findings, generate reports, and more—all through natural language.

### Two Implementations

Both implementations have **complete feature parity** - all features work identically.

| Version | Best For | Size | Install |
|---------|----------|------|---------|
| [**Python**](#python-installation) | Most users, extensibility | ~50MB | `pip install pwndoc-mcp-server` |
| [**Native C++**](#native-installation) | Performance, minimal deps | ~5MB | [Download binary](https://github.com/walidfaour/pwndoc-mcp-server/releases) |

## ✨ Features

- 🔌 **90 MCP Tools** - Complete coverage of PwnDoc API (all endpoints)
- 🔐 **Secure Authentication** - JWT tokens with auto-refresh (both implementations)
- ⚡ **Rate Limiting** - Built-in sliding window rate limiter (both implementations)
- 🔄 **Automatic Retries** - Exponential backoff for failed requests (both implementations)
- 📊 **Comprehensive Logging** - Debug, file, and JSON logging (both implementations)
- 🌍 **Cross-Platform** - Linux, macOS, Windows support
- 🐳 **Docker Ready** - Pre-built container images
- 📦 **Multiple Installation Methods** - pip, apt, yum, binaries
- 🚀 **Two Full Implementations** - Python and C++ with complete feature parity
- 🎯 **Type Safety** - Full mypy type checking (zero errors)
- ✅ **Well Tested** - 111 tests, 100% quality checks passing

## 📥 Installation

### Python Installation

```bash
# Basic installation
pip install pwndoc-mcp-server

# With CLI enhancements
pip install pwndoc-mcp-server[cli]

# With all features
pip install pwndoc-mcp-server[all]
```

**Kali Linux Users:** If you encounter errors during installation, use a virtual environment:

```bash
sudo apt update
sudo apt install -y python3-venv
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install pwndoc-mcp-server
```

### Native Installation

**C++ implementation with complete feature parity** - includes all Python features:
- ✅ Rate limiting with sliding window algorithm
- ✅ Automatic retries with exponential backoff
- ✅ Token refresh using refresh tokens
- ✅ Comprehensive error handling (typed exceptions)
- ✅ Full logging support (info/warning/debug)
- ✅ All 90 MCP tools
- ✅ **Complete CLI Tools** - test, tools, config init, claude-install, claude-status

Download pre-built binaries from [Releases](https://github.com/walidfaour/pwndoc-mcp-server/releases):

| Platform | Binary |
|----------|--------|
| Linux x64 | `pwndoc-mcp-linux-x64` |
| macOS x64 | `pwndoc-mcp-macos-x64` |
| macOS ARM | `pwndoc-mcp-macos-arm64` |
| Windows | `pwndoc-mcp-windows-x64.exe` |

```bash
# Linux/macOS
curl -LO https://github.com/walidfaour/pwndoc-mcp-server/releases/latest/download/pwndoc-mcp-linux-x64
chmod +x pwndoc-mcp-linux-x64
./pwndoc-mcp-linux-x64
```

### Installation Matrix

| Platform | Method | Command |
|----------|--------|---------|
| **Any** | pip | `pip install pwndoc-mcp-server` |
| **Any** | pipx | `pipx install pwndoc-mcp-server` |
| **Linux (Debian/Ubuntu)** | apt | `sudo apt install pwndoc-mcp-server` |
| **Linux (RHEL/CentOS)** | yum | `sudo yum install pwndoc-mcp-server` |
| **macOS** | Homebrew | `brew install pwndoc-mcp-server` |
| **Windows** | Scoop | `scoop install pwndoc-mcp-server` |
| **Any** | Docker | `docker pull ghcr.io/walidfaour/pwndoc-mcp-server` |
| **Any** | Binary | [Download from Releases](https://github.com/walidfaour/pwndoc-mcp-server/releases) |

### From Source

```bash
# Python
git clone https://github.com/walidfaour/pwndoc-mcp-server.git
cd pwndoc-mcp-server/python
pip install -e .[dev]

# Native C++
cd ../native
mkdir build && cd build
cmake .. && make
```

## ⚙️ Configuration

### Quick Start (Interactive Setup)

```bash
pwndoc-mcp config init
```

The interactive wizard will guide you through configuration and support both authentication methods.

### Authentication Methods

You can authenticate using **environment variables**, **config file**, or **CLI arguments**.

**Option 1: Username/Password (Recommended)**
- ✅ Automatically handles token generation and refresh
- ✅ No manual token management required
- ✅ **Preferred** when both credentials and token are provided

```bash
# Environment variables
export PWNDOC_URL="https://pwndoc.example.com"
export PWNDOC_USERNAME="your-username"
export PWNDOC_PASSWORD="your-password"

# Or CLI arguments
pwndoc-mcp serve --url https://pwndoc.example.com --username user --password pass
pwndoc-mcp test --url https://pwndoc.example.com -u user -p pass
```

**Option 2: Pre-authenticated Token**
- Use if you have a JWT token
- ⚠️ Requires manual renewal when expired
- Only used if username/password not provided

```bash
# Environment variables
export PWNDOC_URL="https://pwndoc.example.com"
export PWNDOC_TOKEN="your-jwt-token"

# Or CLI arguments
pwndoc-mcp serve --url https://pwndoc.example.com --token your-jwt-token
```

**Authentication Priority:**
When multiple methods are configured, the system uses this priority:
1. **Username/Password** (if both provided) → automatic token refresh ✅
2. **Token** (if username/password not provided) → manual renewal required ⚠️

This means if you set all three (URL + username/password + token), it will use username/password and ignore the token.

### Configuration File

Create `~/.pwndoc-mcp/config.yaml`:

```yaml
url: https://pwndoc.example.com
username: your-username
password: your-password
verify_ssl: true
timeout: 30
```

## 🖥️ Claude Desktop Integration

### Automatic Installation (Recommended)

```bash
# Configure your PwnDoc credentials
pwndoc-mcp config init

# Automatically install for Claude Desktop
pwndoc-mcp claude-install

# Check installation status
pwndoc-mcp claude-status
```

This will automatically update the appropriate MCP configuration file:
- **Linux**: `~/.config/claude/mcp_servers.json`
- **macOS**: `~/Library/Application Support/Claude/mcp_servers.json`
- **Windows**: `%APPDATA%\Claude\mcp_servers.json`

### Manual Installation

Alternatively, manually add to your Claude Desktop configuration (`claude_desktop_config.json`):

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**Linux**: `~/.config/Claude/claude_desktop_config.json`

### Using Python (pip)

```json
{
  "mcpServers": {
    "pwndoc": {
      "command": "pwndoc-mcp",
      "args": ["serve"],
      "env": {
        "PWNDOC_URL": "https://pwndoc.example.com",
        "PWNDOC_USERNAME": "your-username",
        "PWNDOC_PASSWORD": "your-password"
      }
    }
  }
}
```

### Using Native Binary

```json
{
  "mcpServers": {
    "pwndoc": {
      "command": "/path/to/pwndoc-mcp-linux-x64",
      "env": {
        "PWNDOC_URL": "https://pwndoc.example.com",
        "PWNDOC_TOKEN": "your-token"
      }
    }
  }
}
```

### Using Docker

```json
{
  "mcpServers": {
    "pwndoc": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
        "-e", "PWNDOC_URL=https://pwndoc.example.com",
        "-e", "PWNDOC_TOKEN=your-token",
        "ghcr.io/walidfaour/pwndoc-mcp-server:latest"
      ]
    }
  }
}
```

## 🚀 Usage

### CLI Commands

```bash
# Test connection
pwndoc-mcp test

# List available tools
pwndoc-mcp tools

# Start MCP server
pwndoc-mcp serve

# Interactive config setup
pwndoc-mcp config init

# Claude Desktop integration
pwndoc-mcp claude-install   # Install MCP config for Claude
pwndoc-mcp claude-status    # Check installation status
pwndoc-mcp claude-uninstall # Remove MCP config
```

### Using with Other MCP Clients

The server works with **any MCP-compatible client**, not just Claude Desktop:

**stdio transport (default)** - For client integrations:
```bash
pwndoc-mcp serve  # Communicates via stdin/stdout
```

**SSE transport** - For web-based clients:
```bash
pwndoc-mcp serve --transport sse --host 0.0.0.0 --port 8080
# Access at: http://localhost:8080/mcp
```

**Client configuration examples:**

Cline (VS Code)

Add to Cline MCP settings:
```json
{
  "mcpServers": {
    "pwndoc": {
      "command": "pwndoc-mcp",
      "args": ["serve"],
      "env": {
        "PWNDOC_URL": "https://pwndoc.example.com",
        "PWNDOC_USERNAME": "your-username",
        "PWNDOC_PASSWORD": "your-password"
      }
    }
  }
}
```

Continue.dev

Add to Continue config:
```json
{
  "mcpServers": {
    "pwndoc": {
      "command": "pwndoc-mcp",
      "args": ["serve"]
    }
  }
}
```

Custom MCP Client

Connect to stdio transport:
```python
import subprocess
process = subprocess.Popen(
    ["pwndoc-mcp", "serve"],
    stdin=subprocess.PIPE,
    stdout=subprocess.PIPE,
    env={"PWNDOC_URL": "...", "PWNDOC_USERNAME": "...", "PWNDOC_PASSWORD": "..."}
)
```

Or use SSE transport:
```python
import requests
response = requests.post(
    "http://localhost:8080/mcp",
    json={"method": "tools/list"}
)
```

### Docker

```bash
docker run -it --rm \
  -e PWNDOC_URL="https://pwndoc.example.com" \
  -e PWNDOC_TOKEN="your-token" \
  ghcr.io/walidfaour/pwndoc-mcp-server:latest
```

## 🔧 Available Tools (90)

**Complete coverage of PwnDoc API** - All 92 endpoints exposed as MCP tools (minus 2 internal auth endpoints)

### Audits (13 tools)
- `list_audits` `get_audit` `create_audit` `update_audit_general` `delete_audit`
- `get_audit_general` `get_audit_network` `update_audit_network`
- `get_audit_sections` `update_audit_sections`
- `toggle_audit_approval` `update_review_status` `generate_audit_report`

### Findings (9 tools)
- `get_audit_findings` `get_finding` `create_finding` `update_finding` `delete_finding`
- `sort_findings` `move_finding` `search_findings`
- `get_all_findings_with_context` (comprehensive: extracts CWE, OWASP, strips HTML, full team info)

### Vulnerability Templates (9 tools)
- `list_vulnerabilities` `get_vulnerabilities_by_locale` `create_vulnerability` `update_vulnerability` `delete_vulnerability`
- `bulk_delete_vulnerabilities` `export_vulnerabilities` `create_vulnerability_from_finding`
- `get_vulnerability_updates` `merge_vulnerability`

### Clients & Companies (8 tools)
- `list_clients` `create_client` `update_client` `delete_client`
- `list_companies` `create_company` `update_company` `delete_company`

### Users & Authentication (11 tools)
- `list_users` `get_user` `get_current_user` `create_user` `update_user` `update_current_user`
- `list_reviewers`
- `get_totp_status` `setup_totp` `disable_totp` (2FA/TOTP support)

### Data Types & Configuration (22 tools)
**Languages** (4): `list_languages` `create_language` `update_language` `delete_language`

**Audit Types** (4): `list_audit_types` `create_audit_type` `update_audit_type` `delete_audit_type`

**Vulnerability Types** (4): `list_vulnerability_types` `create_vulnerability_type` `update_vulnerability_type` `delete_vulnerability_type`

**Vulnerability Categories** (4): `list_vulnerability_categories` `create_vulnerability_category` `update_vulnerability_category` `delete_vulnerability_category`

**Sections** (4): `list_sections` `create_section` `update_section` `delete_section`

**Custom Fields** (4): `list_custom_fields` `create_custom_field` `update_custom_field` `delete_custom_field`

### Settings & Templates (10 tools)
- `get_settings` `get_public_settings` `update_settings` `export_settings` `import_settings`
- `list_templates` `create_template` `update_template` `delete_template` `download_template`

### Images (4 tools)
- `get_image` `download_image` `upload_image` `delete_image`

### Statistics & Metadata (4 tools)
- `get_statistics` `list_roles`

> 💡 **Tip:** Use `pwndoc-mcp tools` to list all available tools with descriptions

[Full tool documentation →](https://walidfaour.github.io/pwndoc-mcp-server/tools/overview)

## 📖 Documentation

- **GitHub Pages**: [walidfaour.github.io/pwndoc-mcp-server](https://walidfaour.github.io/pwndoc-mcp-server)
- **Repository docs**: [docs/](./docs/)

Quick links:
- [Getting Started Guide](https://walidfaour.github.io/pwndoc-mcp-server/getting-started/quick-start)
- [Configuration Reference](https://walidfaour.github.io/pwndoc-mcp-server/getting-started/configuration)
- [Tool Reference](https://walidfaour.github.io/pwndoc-mcp-server/tools/overview)
- [Docker Deployment](https://walidfaour.github.io/pwndoc-mcp-server/user-guide/docker)

## 📁 Project Structure

```
pwndoc-mcp-server/
├── python/                   # Python implementation
│   ├── src/pwndoc_mcp_server/
│   ├── tests/
│   ├── pyproject.toml
│   └── Dockerfile
├── native/                   # C++ implementation
│   ├── src/
│   ├── include/
│   └── CMakeLists.txt
├── docs/                     # Documentation
├── assets/                   # Branding assets
├── debian/                   # Debian packaging
├── rpm/                      # RPM packaging
├── packaging/                # Homebrew/Scoop
└── .github/                  # CI/CD workflows
```

## 🔒 Security

See [SECURITY.md](SECURITY.md) for reporting vulnerabilities.

**Important:** This tool handles sensitive penetration testing data. Use only on authorized systems.

## 🤝 Contributing

Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

```bash
# First, configure git
git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# Clone and setup
git clone https://github.com/walidfaour/pwndoc-mcp-server.git
cd pwndoc-mcp-server/python
pip install -e .[dev]
pytest
```

## 📜 License

MIT License - see [LICENSE](LICENSE) for details.

## 🙏 Acknowledgments

- [PwnDoc](https://github.com/pwndoc/pwndoc) - The penetration testing documentation platform
- **Walid Faour** - security@walidfaour.com

---

  Made with ❤️ by Walid Faour

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [walidfaour](https://github.com/walidfaour)
- **Source:** [walidfaour/pwndoc-mcp-server](https://github.com/walidfaour/pwndoc-mcp-server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-walidfaour-pwndoc-mcp-server
- Seller: https://agentstack.voostack.com/s/walidfaour
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.