bunkerity/bunkerweb-mcp

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 BUNKERWEBBASEURL 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 MCPALLOWEDHOSTS=localhost,localhost:8080,127.0.0.1,127.0.0.1:8080 for
local HTTP clients. Keep SEARCHMODE=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:
json
"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": " "} 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:
bash
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.