Bunkerweb MCP

BunkerWeb MCP Server

Expose the BunkerWeb API to MCP clients through tools, read-only resources, and tool guidance prompts.

Website | BunkerWeb documentation | Quick start | Client setup

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.

You need a reachable BunkerWeb API and its credentials when authentication is enabled. See the BunkerWeb documentation for API setup.

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. The demo publishes /mcp/ on port 8080 on all interfaces without a client token check.

This file sets the API URL and demo credentials in its service definitions; editing .env does not replace those values. It also disables search and MCP DNS rebinding protection. Use it on a trusted development machine; review credentials, port exposure, and host validation before exposing it to a network.

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.

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.

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.

Tools and resources

Read GET /tools for the running server's tool names, descriptions, and input schemas. The registry defines 44 API tools:

Optional tools:

• logs_list, logs_read: 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.

Use diagnose 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 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. For example, 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.

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

The MCP adapter also exposes read-only resources:

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

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.

Security

Tools can change configuration, stop instances, delete services, and install plugins. Grant access only to clients you trust with the configured BunkerWeb API credentials. Set MCP_READ_ONLY=true to serve only read tools on every transport. The server has no per-client roles.

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.

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.