bunkerweb-mcp

<p align="center"> <a href="https://www.bunkerweb.io"> <img alt="BunkerWeb logo" src="https://github.com/bunkerity/bunkerweb/raw/v1.6.17-rc1/misc/logo.png" width="350" /> </a> </p> <h1 align="center">BunkerWeb MCP Server</h1> <p align="center"> Expose the BunkerWeb API to MCP clients through tools, read-only resources, and tool guidance prompts. </p> <p align="center"> <a href="https://github.com/bunkerity/bunkerweb-mcp/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/bunkerity/bunkerweb-mcp/actions/workflows/ci.yml/badge.svg" /></a> <a href="https://score.getplumber.io/github.com/bunkerity/bunkerweb-mcp"><img alt="Plumber CI/CD security score" src="https://score.getplumber.io/github.com/bunkerity/bunkerweb-mcp.svg" /></a> <a href="https://securityscorecards.dev/viewer/?uri=github.com/bunkerity/bunkerweb-mcp"><img alt="OpenSSF Scorecard" src="https://api.securityscorecards.dev/projects/github.com/bunkerity/bunkerweb-mcp/badge" /></a> <a href="https://glama.ai/mcp/servers/bunkerity/bunkerweb-mcp"><img alt="Glama MCP server score" src="https://glama.ai/mcp/servers/bunkerity/bunkerweb-mcp/badges/score.svg" /></a> <a href="https://hub.docker.com/r/bunkerity/bunkerweb-mcp"><img alt="Docker pulls" src="https://img.shields.io/docker/pulls/bunkerity/bunkerweb-mcp" /></a> <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg" /></a> </p> <p align="center"> <a href="https://www.bunkerweb.io">Website</a> &#124; <a href="https://docs.bunkerweb.io">BunkerWeb documentation</a> &#124; <a href="#quick-start">Quick start</a> &#124; <a href="#connect-an-mcp-client">Client setup</a> </p>

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.

| Environment variable | Default | Meaning | | --- | --- | --- | | BUNKERWEB_BASE_URL | http://localhost:8888 | Base URL for the BunkerWeb control-plane API. | | BUNKERWEB_API_TOKEN | unset | Static API token used for Authorization bearer header (masked in logs). | | BUNKERWEB_BASIC_USERNAME | unset | Username for HTTP Basic authentication. | | BUNKERWEB_BASIC_PASSWORD | unset | Password for HTTP Basic authentication (masked in logs). | | BUNKERWEB_REQUEST_TIMEOUT_SECONDS | 30.0 | HTTP request timeout in seconds. | | BUNKERWEB_MAX_RETRIES | 3 | Maximum number of retries for transient HTTP errors. | | BUNKERWEB_RETRY_BACKOFF_INITIAL | 0.5 | Initial backoff delay in seconds. | | BUNKERWEB_RETRY_BACKOFF_MAX | 5.0 | Maximum backoff delay in seconds. | | BUNKERWEB_WEBSOCKET_TOKEN | unset | Shared secret for legacy RPC/WebSocket access; also required on MCP HTTP when runtime logs are enabled. See Security. | | BUNKERWEB_LOG_LEVEL | INFO | Application log level. | | BUNKERWEB_LOGS_PATH | unset | Runtime log directory; unset disables log tools. Mount read-only. | | BUNKERWEB_PROMPT_CATALOG | unset | Custom tool-prompt JSON path; unset uses the bundled catalog. | | BUNKERWEB_REDACT_SECRETS | false | Mask the values of settings whose names match a sensitive pattern in tool and resource outputs, withhold upstream error details and refuse writes to sensitive settings. See Security. | | BUNKERWEB_REDACT_PATTERN | unset | Regular expression that replaces the built-in sensitive setting name pattern; unset keeps the built-in one. Avoid nested quantifiers such as (a+)+$. | | SEARCH_MODE | remote | remote enables documentation search; disabled omits the tool. Compose and .env.example use disabled. | | SEARCH_API_URL | http://localhost:8000 | URL of the remote search service API. | | SEARCH_TIMEOUT | 10.0 | Search API request timeout in seconds. | | MCP_ENABLE_DNS_REBINDING_PROTECTION | true | Enable DNS rebinding protection for MCP endpoints (recommended for production). | | MCP_ALLOWED_HOSTS | localhost,127.0.0.1 | Comma-separated MCP Host allowlist. Include the port variants clients send. | | MCP_ALLOWED_ORIGINS | unset | Comma-separated MCP Origin allowlist for browser clients. | | MCP_ENABLE_SKILLS | true | Serve bundled Agent Skills as skill://bunkerweb/ resources. Set false to omit them. | | MCP_READ_ONLY | false | Register only read-only tools; write tools are not available on any transport. | | RATE_LIMIT_ENABLED | false | Enable rate limiting on endpoints. | | RATE_LIMIT_TOOLS | 30/minute | Requests to /tools per client IP, when rate limiting is enabled. | | RATE_LIMIT_RPC | 100/minute | Requests to /rpc per client IP, when rate limiting is enabled. | | RATE_LIMIT_WS | 500/minute | Messages per WebSocket connection, when rate limiting is enabled. | | CACHE_ENABLED | true | Cache selected read operations in process memory. |

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:

| Group | Tools | | --- | --- | | Authentication and probes | authenticate, ping, health, diagnose | | Instances | list_instances, instance_get, instance_create, instance_update, instance_delete, instances_delete_bulk, instance_ping, instances_ping_all, instance_stop, instances_stop_all, reload_instance, reload_instances | | Bans | list_bans, ban_ip, unban_ip | | Services | list_services, get_service, create_service, update_service, delete_service, convert_service | | Global configuration | global_config_read, global_config_update | | Custom configuration | configs_list, config_get, config_create, config_update, config_delete, configs_delete_bulk, configs_upload, config_upload_update | | Plugins | plugins_list, plugins_upload, plugin_delete | | Job cache files | cache_list, cache_fetch_file, cache_delete_file, cache_delete_bulk | | Scheduler jobs | jobs_list, jobs_run |

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