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. 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	Most users, extensibility	~50MB	`pip install pwndoc-mcp-server`
Native C++	Performance, minimal deps	~5MB	Download binary

✨ 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

# 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:

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:

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`

# 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

From Source

# 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)

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

# 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

# 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:

Username/Password (if both provided) → automatic token refresh ✅
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:

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

🖥️ Claude Desktop Integration

Automatic Installation (Recommended)

# 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)

{
  "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

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

Using Docker

{
  "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

# 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:

pwndoc-mcp serve  # Communicates via stdin/stdout

SSE transport - For web-based clients:

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:

{
  "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:

{
  "mcpServers": {
    "pwndoc": {
      "command": "pwndoc-mcp",
      "args": ["serve"]
    }
  }
}

Custom MCP Client

Connect to stdio transport:

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:

import requests
response = requests.post(
    "http://localhost:8080/mcp",
    json={"method": "tools/list"}
)

Docker

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 →

📖 Documentation

GitHub Pages: walidfaour.github.io/pwndoc-mcp-server
Repository docs: docs/

Quick links:

📁 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 for reporting vulnerabilities.

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

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

# 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 for details.

🙏 Acknowledgments

PwnDoc - The penetration testing documentation platform
Walid Faour - security@walidfaour.com

Made with ❤️ by Walid Faour

Name		Name	Last commit message	Last commit date
Latest commit History 163 Commits
.github		.github
assets		assets
debian		debian
docs		docs
native		native
packaging		packaging
python		python
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
COMPARISON.md		COMPARISON.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
mcp-registry.json		mcp-registry.json

Folders and files

Latest commit

History

Repository files navigation

PwnDoc MCP Server

🎯 Overview

Two Implementations

✨ Features

📥 Installation

Python Installation

Native Installation

Installation Matrix

From Source

⚙️ Configuration

Quick Start (Interactive Setup)

Authentication Methods

Configuration File

🖥️ Claude Desktop Integration

Automatic Installation (Recommended)

Manual Installation

Using Python (pip)

Using Native Binary

Using Docker

🚀 Usage

CLI Commands

Using with Other MCP Clients

Docker

🔧 Available Tools (90)

Audits (13 tools)

Findings (9 tools)

Vulnerability Templates (9 tools)

Clients & Companies (8 tools)

Users & Authentication (11 tools)

Data Types & Configuration (22 tools)

Settings & Templates (10 tools)

Images (4 tools)

Statistics & Metadata (4 tools)

📖 Documentation

📁 Project Structure

🔒 Security

🤝 Contributing

📜 License

🙏 Acknowledgments

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 11

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages