BunkerWeb MCP

If you installed the package locally (pip install -e .), Claude Code and VS Code can launch the server as a subprocess via stdio, without Docker.

Configuration examples for Claude Code, VS Code, and Claude Desktop are in the dedicated section:MCP integration > Stdio Transport.

Important: use theabsolute pathto the virtualenv binary incommand(get it withwhich bunkerweb-mcp). Relative commands can fail because MCP clients do not inherit your shell PATH.

The server supports multiple transport protocols for MCP clients:

Stdio Transport (Recommended for Claude Code and VS Code)

{ "mcpServers": { "bunkerweb": { "type": "stdio", "command": "/path/to/your/.venv/bin/bunkerweb-mcp", "env": { "BUNKERWEB_BASE_URL": "http://<bunkerweb-api-host>:8888", "BUNKERWEB_API_TOKEN": "your-api-token-here" } } } }

{ "servers": { "bunkerweb": { "type": "stdio", "command": "/path/to/your/.venv/bin/bunkerweb-mcp", "env": { "BUNKERWEB_BASE_URL": "http://<bunkerweb-api-host>:8888", "BUNKERWEB_API_TOKEN": "your-api-token-here" } } } }

Adaptcommandto your actual virtualenv path (which bunkerweb-mcpafter activating it) and setBUNKERWEB_BASE_URLto your BunkerWeb API address.

ForClaude Desktop, add the same block to yourclaude_desktop_config.json(macOS:~/Library/Application Support/Claude/claude_desktop_config.json, Linux:~/.config/Claude/claude_desktop_config.json) — thetypefield can be omitted as Desktop defaults to stdio:

{ "mcpServers": { "bunkerweb": { "command": "/path/to/your/.venv/bin/bunkerweb-mcp", "env": { "BUNKERWEB_BASE_URL": "http://<bunkerweb-api-host>:8888", "BUNKERWEB_API_TOKEN": "your-api-token-here" } } } }

Verify the server is detected by Claude Code:

claude mcp list # bunkerweb: /path/to/your/.venv/bin/bunkerweb-mcp (stdio)

Note: The stdio transport runs the server as a subprocess communicating via stdin/stdout — no port, no Docker required.

Point MCP-compatible clients at the streamable HTTP endpoint:

- Transport: Streamable HTTP
- URL:http://localhost:8080/mcp

{ "mcpServers": { "bunkerweb": { "url": "http://localhost:8080/mcp", "transport": "http" } } }

Legacy JSON-RPC transports remain available for existing workflows:

- HTTP:/rpcendpoint
- WebSocket:/wsendpoint

Use theBUNKERWEB_WEBSOCKET_TOKENvalue when a client requires authentication; the same secret protects all transports.

The server exposes read-only resources that can be referenced in Claude Code conversations using the@syntax:

> Review @config://global and suggest security hardening improvements > Check @bans://active for any suspicious patterns

The MCP server uses an AI-powered semantic search tool for BunkerWeb documentation via a remote search service.

⚠️ IMPORTANT: The search functionality has been externalized to a separate service for better scalability and reduced image size.It is not yet available to the public

# Enable or disable search SEARCH_MODE=disabled # 'remote' or 'disabled' # Search service URL SEARCH_API_URL=https://search.example.com # Request timeout SEARCH_TIMEOUT=10.0

The includeddocker-compose.ymldisables search because no search container is bundled. To use a deployed search service, setSEARCH_MODE=remoteand provide itsSEARCH_API_URL.

Query the/toolsendpoint for JSON descriptors. Available tools include:

- search_bunkerweb_docs: Semantic search across BunkerWeb documentation (query,limit,category)

- ping: Check API reachability
- health: Read the API health probe
- list_instances: List registered BunkerWeb instances
- reload_instances: Reload configuration across all instances (testflag supported)
- reload_instance: Reload a specific instance (hostname, optionaltest)

- list_bans: Retrieve active bans
- ban_ip: Ban one or multiple IPs (bansarray withip,exp,reason,service)
- unban_ip: Remove bans (bansarray withip, optionalservice)

- list_services: List services (with_draftsflag)
- get_service: Fetch details for a specific service (service,full,methods,with_drafts)
- delete_service: Delete a service (service)

And 32 more built-in tools covering authentication, configs, plugins, jobs, and cache management.

Each descriptor now carries apromptfield sourced from the prompt catalog. MCP clients can surface these short instructions to keep assistant answers consistent across tools.

The package ships withbunkerweb_mcp/data/tool_prompts.json, a curated set of guidance strings keyed by tool name. At startup the catalog is loaded once and injected into tool descriptors as well as every RPC/WebSocket response. Override the location withBUNKERWEB_PROMPT_CATALOGif you need custom wording.

curl -X POST http://localhost:8080/rpc \ -H "Content-Type: application/json" \ -H "X-MCP-Token: $BUNKERWEB_WEBSOCKET_TOKEN" \ -d '{"id":"1","tool":"list_instances","params":{}}

echo '{"id":"ping-1","tool":"ping","params":{}}' \ | websocat -H "Sec-WebSocket-Protocol: json" ws://localhost:8080/ws?token=$BUNKERWEB_WEBSOCKET_TOKEN

pip install -r requirements-dev.txt pytest

src/bunkerweb_mcp/ ├─ main.py # FastAPI app + JSON-RPC endpoints ├─ cli.py # CLI entry point for stdio mode ├─ mcp_adapter.py # MCP server integration ├─ client.py # Resilient async client for BunkerWeb ├─ tools/ # MCP tools with strict validation ├─ config.py # Environment-driven settings ├─ prompt_catalog.py # Prompt loading helpers ├─ exceptions.py # Domain-specific exceptions ├─ search_client.py # Lightweight HTTP client for search service ├─ schemas/ # Pydantic models for requests/responses └─ utils/logging.py # Structured logging helpers src/bunkerweb_mcp/data/ └─ tool_prompts.json # Default tool prompts exposed to MCP clients

The MCP server includes comprehensive observability features:

Metrics are exposed atGET /metricsin Prometheus format:

- mcp_tool_calls_total{tool_name, status}- Total tool calls by status
- mcp_tool_duration_seconds- Tool execution duration histogram
- mcp_active_websockets- Active WebSocket connections
- bunkerweb_api_requests_total{endpoint, method, status}- BunkerWeb API requests
- bunkerweb_api_errors_total{endpoint, error_type}- API errors
- mcp_cache_hits_total{cache_type}- Cache hits
- mcp_cache_misses_total{cache_type}- Cache misses
- mcp_search_queries_total{mode, status}- Search queries

Distributed tracing with automatic instrumentation:

# Configure tracing via environment variables OTEL_TRACING_ENABLED=true OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger:4317

- HTTP requests (FastAPI)
- Outgoing API calls (httpx)
- Tool executions

Liveness probe- Checks if the server is running:

curl http://localhost:8080/health # Response: {"status": "healthy", "timestamp": "..."}

Readiness probe- Checks if the server can handle requests:

curl http://localhost:8080/ready # Response: {"status": "ready", "checks": {"bunkerweb_api": true, "search_service": true}, "timestamp": "..."}

livenessProbe: httpGet: path: /health port: 8080 initialDelaySeconds: 10 periodSeconds: 30 readinessProbe: httpGet: path: /ready port: 8080 initialDelaySeconds: 5 periodSeconds: 10

Start the full observability stack (Prometheus, Grafana, Jaeger):

docker-compose -f docker-compose.monitoring.yml up -d

Import fromdeploy/grafana/dashboards/mcp-bunkerweb.json

Pre-configured Prometheus alerts indeploy/prometheus/alerts.yml:

- High tool error rate (>10%)
- High latency (P95 > 5s)
- BunkerWeb API errors
- Low cache hit rate (<30%)
- Service health issues

Logs are emitted as single-line JSON for ingestion by log processors. Eachtool_calllog carries ametricsobject with the tool name andduration_secondsfor latency tracking. AdjustBUNKERWEB_LOG_LEVELas needed.

The MCP server includes several performance optimizations introduced in Sprint 2:

Enabled by default- Caches read-only API operations to reduce latency and load on BunkerWeb API.

# Configure in .env CACHE_ENABLED=true # Default: true

Cache TTLs(configured insrc/bunkerweb_mcp/cache.py):