BunkerWeb MCP

Manage services, instances, bans, configuration snippets, plugins, and scheduler jobs. Connect through streamable HTTP or a local stdio subprocess. Legacy JSON-RPC HTTP and WebSocket endpoints remain available for existing integrations.

How it fits together

The server holds no BunkerWeb state. It turns each tool call into a request to the BunkerWeb API.

Related MCP server: Developer Toolbox MCP

Quick start

Connect to an existing BunkerWeb API

1. Clone this repository and open its directory.

2. Copy .env.example to .env. Set BUNKERWEB_BASE_URL to an API address reachable from the container, and supply its bearer token or Basic credentials. A container's localhost refers to itself.

3. Set MCP_ALLOWED_HOSTS=localhost,localhost:8080,127.0.0.1,127.0.0.1:8080 for local HTTP clients. Keep SEARCH_MODE=disabled unless you have a search service.

4. Run docker compose -f docker-compose-mcp-only.yml up --build -d.

5. Check liveness with curl http://127.0.0.1:8080/health; expect "status":"healthy".

6. Connect your client to http://127.0.0.1:8080/mcp/.

The MCP-only Compose file loads .env, builds the server, and publishes port 8080. For the published image instead, run docker run --rm -p 127.0.0.1:8080:8080 --env-file .env bunkerity/bunkerweb-mcp:latest. Use a release tag for a fixed version; the release workflow builds images for AMD64 and ARM64.

Try the bundled demo stack

Run docker compose up --build -d from the repository directory. The default docker-compose.yml starts BunkerWeb 1.6.13, its scheduler and API, MariaDB, Redis, and this server. It publishes BunkerWeb on ports 80/443 and MCP on 8080. The included .mcp.json points Claude Code at this server.

Connect an MCP client

Streamable HTTP

Use /mcp/, including the trailing slash. The repository's Claude Code config uses:

{
  "mcpServers": {
    "bunkerweb": {
      "type": "http",
      "url": "http://127.0.0.1:8080/mcp/"
    }
  }
}

For a remote server, change the URL to your HTTPS endpoint. When runtime log access is enabled, add "headers": {"x-mcp-token": "<shared-secret>"} inside the server entry. Read the authentication limits in Security before exposing HTTP.

Stdio: Claude Code or Claude Desktop

From the repository directory, install with Python 3.11 or newer using the hash-pinned build and runtime dependencies:

python3 -m venv .venv
.venv/bin/pip install --require-hashes --no-deps -r requirements-build.txt -r requirements.txt
.venv/bin/pip install --no-deps --no-build-isolation .

This creates .venv/bin/bunkerweb-mcp in your checkout. Use its absolute path in the client JSON below, replacing /absolute/path/to with your repository directory. It runs a stdio subprocess without an HTTP listener.

For Claude Code, replace the HTTP entry in .mcp.json with this configuration. For Claude Desktop, put it in claude_desktop_config.json:

{
  "mcpServers": {
    "bunkerweb": {
      "command": "/absolute/path/to/.venv/bin/bunkerweb-mcp",
      "env": {
        "BUNKERWEB_BASE_URL": "http://api.example.com:8888",
        "BUNKERWEB_API_TOKEN": "<api-token>",
        "SEARCH_MODE": "disabled"
      }
    }
  }
}

Replace the executable path and API address with your own. Keep real credentials out of version control. Stdio uses your local process permissions and API credentials.

Tools and resources

Read GET /tools for the running server's tool names, descriptions, and input schemas. The registry defines 36 API tools, all named verb_noun (ADR 0007):

Optional tools:

• list_logs, read_log: register when BUNKERWEB_LOGS_PATH points to a runtime log directory. Mount it read-only; HTTP mode also requires the shared secret. Reads scan up to 1 MiB and return at most 500 lines or 64 KiB of content, with cursors for older history. Compressed .gz rotations are excluded. Treat log content as untrusted data.

• search_bunkerweb_docs: registers in remote search mode.

Tool behavior

Use diagnose_bunkerweb to check the connected API's host, reachability, authentication, version, MULTISITE, and instance counts. Pass service to inspect its existence, draft state, and setting-owner counts. An unknown version appears as unknown (strictest rules applied).

update_service validates, writes, then reads back:

• It checks setting names and ownership before sending changes. It refuses the request if validation reads fail or MULTISITE is not yes. It skips invalid or externally owned keys and unsupported renames; if nothing remains, it sends no write.

• After an accepted write, it reads the service back without the result cache. The result adds summary as its first field and a receipt with db (verified, partial, or unverified), plus issues and hints when needed. These report names and reasons, without setting values.

• A complete match reads DB VERIFIED (2/2 MATCH). LIVE UNVERIFIED. A failed read-back reads WRITE ACCEPTED. DB UNVERIFIED. LIVE UNVERIFIED. Only a read-back that confirms a draft adds DRAFT: NOT PUBLISHED. A failed read-back omits the draft marker.

• The summary always ends LIVE UNVERIFIED. BunkerWeb 1.6 offers no live-state signal; the receipt does not prove that instances use the saved configuration.

stop_instances and reload_instances need exactly one of hostname or all=true; any other combination fails validation and sends nothing to BunkerWeb. delete_instances, delete_configs and delete_cache_files take a list and always call the bulk endpoint. update_service with is_draft toggles a service between draft and online.

Tool metadata identifies reads and destructive writes. MCP_READ_ONLY=true removes write tools and their prompts on every transport, including create_api_token, which returns a credential. See ADR 0006 for the version rules and enforcement boundary.

Resources

The MCP adapter also exposes read-only resources:

The first four resources return JSON. Skill resources register when MCP_ENABLE_SKILLS=true.

Prompts

Tool guidance comes from the bundled prompt catalog. The server exposes matching MCP prompts when catalog text exists. Override the catalog with BUNKERWEB_PROMPT_CATALOG.

Examples and legacy workflow integrations live in n8n-workflows.

Agent Skills

The server bundles 13 BunkerWeb Agent Skills (59 files), available through MCP resources/list and resources/read. Start with skill://bunkerweb/bunkerweb/SKILL.md; the server's initialization instructions point there too. This entrypoint links to the other 12 skills on GitHub and to its bundled references/ files.

Read bundled files at skill://bunkerweb/<skill>/<path>, for example skill://bunkerweb/bunkerweb/references/docker.md. Files are served verbatim, with text/markdown for .md files. Set MCP_ENABLE_SKILLS=false to omit skill resources and the skills sentence from the server instructions.

Skills come from bunkerity/bunkerweb-skills, pinned by SKILLS_REF. Refresh with scripts/sync_skills.py --ref <sha>; CI runs the script with --check to detect drift.

Configuration

config.py reads environment variables and .env. Defaults below come from that settings model; Compose service values and container environment variables can override them. unset denotes an absent value or an empty string.

WORKERS is a Docker entrypoint setting, default 1, rather than a Pydantic setting. Caches and rate-limit state live in each worker process.

Documentation search

Search needs a separate service: set SEARCH_MODE=remote and SEARCH_API_URL to its URL. This repository does not bundle that service. Without it, disable search; otherwise the server registers search_bunkerweb_docs and readiness checks the service.

Security

The HTTP application implements these shared-secret checks:

HTTP startup fails if you configure runtime logs without a non-empty shared secret. BUNKERWEB_API_TOKEN and Basic credentials authenticate the server to BunkerWeb; they do not authenticate MCP clients. The API client prefers a bearer token over Basic auth.

Keep HTTP on a trusted network or behind an authenticated reverse proxy. Use TLS for remote connections, restrict the exposed endpoints, and configure MCP_ALLOWED_HOSTS and MCP_ALLOWED_ORIGINS for your clients. DNS rebinding protection does not replace authentication. See docs/security.md.

Secret redaction

Set BUNKERWEB_REDACT_SECRETS=true to mask the values of sensitive settings (matched by name) in tool and resource outputs before they reach the client. Upstream API error details are withheld and only the HTTP status is returned. It is not a content scanner: custom config snippets, log lines, documentation search results, cache files outside the denylist and secrets embedded in other values are not masked. See docs/security.md.

Observability

The HTTP server exposes Prometheus metrics at /metrics, liveness at /health, and dependency readiness at /ready. Readiness probes BunkerWeb's /ping without API credentials and, in remote search mode, the search service's /health; a protected API can therefore fail readiness even when authenticated tools work.

See docs/OBSERVABILITY.md for metrics, tracing, and dashboard reference. Grafana dashboards: BunkerWeb MCP and MCP BunkerWeb. Tracing is opt-in; this repository does not include a monitoring Compose stack.

Development

Use the hash-pinned build and development dependencies before installing this package from source. AGENTS.md contains installation, lint, formatting, strict type-checking, and test commands. Tests mock upstream HTTP calls and enforce an 80% coverage floor.

.pre-commit-config.yaml checks YAML/TOML, file hygiene, and Python lint/formatting. Run pre-commit install to install the local hooks. The architecture decisions record design context. docs/tdqs.md explains the Glama quality score and how to run the same scorer locally with scripts/tdqs.py before changing tool descriptions.

Supply chain

• Build, runtime, and development dependencies use hash-pinned requirements-build.txt, requirements.txt, and requirements-dev.txt locks. Edit their .in sources and regenerate with the uv commands in AGENTS.md; do not hand-edit generated locks.

• CI runs quality checks, tests on Python 3.11–3.14, CodeQL, and container checks. Plumber checks CI/CD security; OpenSSF Scorecard analyzes repository security practices. Badges link to published results.

• The release workflow requests build provenance and an SBOM for Docker images.

• Follow .github/SECURITY.md to report vulnerabilities.

License

MIT. See LICENSE.