mcp-api-pentest

An MCP server that lets AI assistants (Claude Desktop, Cursor, Claude Code) perform automated security audits on your APIs. It detects BOLA/IDOR vulnerabilities — the #1 risk in the OWASP API Top 10 — where one user can access another user's data.

Think of it as giving your AI the ability to act like a penetration tester, running requests with different user tokens and comparing the results to find broken authorization logic.

Quickstart in 3 minutes

# 1. Clone and install
git clone https://github.com/josenieto/mcp-api-pentest
cd mcp-api-pentest
uv sync

# 2. Start the mock API (a vulnerable API for safe testing)
uv run mock_api.py

# 3. Start the MCP server
uv run app.py

That's it. The server is now running and waiting for an AI client to connect.

Related MCP server: MCPPentestBOT

What it does

The project acts as a bridge between an AI and your API:

AI (Claude/Cursor)  ←→  MCP Server  ←→  API Target
                           |
                     Generates REPORTE_PENTEST.md

Example attack flow the AI can run:

1. Create an invoice with Token A → POST /api/v1/invoices

2. Read the same invoice with Token B → GET /api/v1/invoices/42

3. Detect the IDOR → both tokens return 200 OK with 94% similar content

4. Save the finding → "BOLA/IDOR in invoices endpoint — CRITICAL"

5. Generate a report → REPORTE_PENTEST.md

All of this happens without writing a single line of code — the AI drives the audit through MCP tools.

Features

• IDOR detection: Compares API responses with privileged vs unprivileged tokens

• Chained attacks: Create a resource, capture its ID, then attack it with a different user

• Multi-session state: Cache dynamic values across requests for complex attack flows

• Smart truncation: Handles massive JSON responses without flooding the AI's context window

• Rate limiting: Passive delays to avoid being blocked by WAFs

• Intelligent retry: Detects 429 responses and retries with exponential backoff

• Multiple auth schemes: Bearer, Basic, API Key (header/query), Cookie

• Stealth mode: Random delay between requests to evade WAF detection patterns

• User-Agent rotation: Rotates through a pool of realistic browser User-Agents

• OpenAPI 3.x + YAML: Parses Swagger 2.0, OpenAPI 3.x in JSON or YAML format

• Markdown reports: Automatic generation of security audit reports with evidence

• Mock API sandbox: 9 intentionally vulnerable endpoints for safe testing

• CLI entry point: Run from the terminal with mcp-api-pentest --target https://api.example.com

Installation

From source (recommended for now)

git clone https://github.com/josenieto/mcp-api-pentest
cd mcp-api-pentest
uv sync

Requirements

• Python 3.10 or newer

• uv package manager

How to Use

Option 1: CLI mode (terminal)

Start the MCP server directly:

uv run app.py

With options:

mcp-api-pentest \
  --swagger spec.json \
  --target https://api.example.com \
  --token-admin "admin123" \
  --token-victim "victim456" \
  --token-attacker "attacker789" \
  --output report.md \
  --delay 1.0

Option 2: Connect an AI client

Add this to your MCP client configuration:

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "api-logic-pentest": {
      "command": "uv",
      "args": ["run", "app.py"],
      "cwd": "/path/to/mcp-api-pentest"
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "api-logic-pentest": {
      "command": "uv",
      "args": ["run", "app.py"],
      "cwd": "/path/to/mcp-api-pentest"
    }
  }
}

Claude Code (~/.claude/mcp.json):

{
  "mcpServers": {
    "api-logic-pentest": {
      "command": "uv",
      "args": ["run", "app.py"],
      "cwd": "/path/to/mcp-api-pentest"
    }
  }
}

Option 3: Sandbox mode (test locally)

# Starts a vulnerable mock API on port 8080
uv run mock_api.py

The mock API includes 3 test users with tokens:

Vulnerable endpoints (intentionally broken for testing):

• GET /api/v1/facturas/{id} — IDOR (no ownership validation)

• POST /api/v1/invoices — creates invoice, captures ID for chained attacks

• DELETE /api/v1/invoices/{id} — deletes without ownership check

• GET /api/v1/users/{id}/profile — reads profile without ownership check

• PUT /api/v1/users/{id}/profile — mass assignment without ownership (escalate role to admin)

• GET /api/v1/items — pagination without bounds validation

• POST /api/v1/items — creates item for chained attacks

• DELETE /api/v1/items/{id} — deletes without ownership check

• GET /api/v1/spec.yaml — returns OpenAPI 3.x spec in YAML format

Running Tests

# Run all tests (141 tests, all passing)
uv run pytest

# Run with verbose output
uv run pytest -v

# Run tests for a specific module
uv run pytest src/mcp_api_pentest/idor_detector/tests/

Code quality checks:

# Lint
uv run ruff check .

# Type checking
uv run mypy src/mcp_api_pentest/ --ignore-missing-imports

Available MCP Tools

The AI can use 11 tools to audit APIs:

Architecture

This project follows a Modular Monolith by Features design.

src/mcp_api_pentest/
├── config/               → Global settings and logger
├── shared/               → Reusable utilities (JSON truncation)
├── spec_analyzer/        → OpenAPI/Swagger file parsing
├── http_client/          → HTTP communication with auth providers
├── idor_detector/        → Multi-session authorization comparison
├── audit_context/        → In-memory state for chained attacks
├── report_generator/     → Security finding reports (Markdown + JSON)
├── orchestration/        → Cross-module attack flow coordinator
└── adapters/             → Entry points: MCP server and CLI

Each module is self-contained with its own tests. New detection patterns (like Mass Assignment or Rate Limit testing) are added as new modules without touching existing code.

See docs/adr/ADR-001-modular-monolith-by-features.md for the full architecture decision.

Contributing

1. Create a branch from integration/master

2. Write your changes plus tests (we follow RED/GREEN/REFACTOR)

3. Push — CI runs lint, type check, and tests automatically

4. When CI passes, the merge happens automatically

License

MIT