arcane-mcp

A Docker-hostable MCP server for Arcane. It reads your Arcane instance's OpenAPI spec at startup and exposes the Docker-management API (containers, images, volumes, networks, Compose projects, environments, system) as MCP tools over Streamable HTTP. Because tools are generated from the live spec, they track your Arcane version automatically.

Quick start

Prebuilt multi-arch images (amd64, arm64) are published to GitHub Container Registry on every push to main and every v* tag: ghcr.io/lukeeexd/arcane-mcp. No clone or local build is needed.

mkdir arcane-mcp && cd arcane-mcp
curl -fsSLO https://raw.githubusercontent.com/lukeeexd/arcane-mcp/main/compose.yaml
curl -fsSL  https://raw.githubusercontent.com/lukeeexd/arcane-mcp/main/.env.example -o .env
# edit .env: set ARCANE_BASE_URL, ARCANE_API_KEY, MCP_AUTH_TOKEN
docker compose up -d
curl http://localhost:8000/health

Or without compose:

docker run -d --name arcane-mcp --restart unless-stopped -p 8000:8000 \
  -e ARCANE_BASE_URL=https://arcane.example.com \
  -e ARCANE_API_KEY=arc_xxx \
  -e MCP_AUTH_TOKEN=change-me \
  ghcr.io/lukeeexd/arcane-mcp:latest

Tags: latest tracks main; releases are tagged 1.2.3 and 1.2; every build also gets sha-<short>. To build locally instead, run docker build -t arcane-mcp:local . and point image: in compose.yaml at it.

Create the Arcane API key in Arcane under your profile, or via POST /api/auth/me/api-keys. Generate MCP_AUTH_TOKEN with openssl rand -hex 32.

Without Docker:

uv sync
ARCANE_BASE_URL=... ARCANE_API_KEY=... MCP_AUTH_TOKEN=... uv run arcane-mcp

Related MCP server: docker-mcp

Connecting a client

Claude Code:

claude mcp add --transport http arcane http://<host>:8000/mcp --header "Authorization: Bearer <MCP_AUTH_TOKEN>"

Any other MCP client: Streamable HTTP endpoint http://<host>:8000/mcp, header Authorization: Bearer <MCP_AUTH_TOKEN>.

How it works

1. On boot the server fetches ARCANE_BASE_URL/api/openapi.json, retrying for ARCANE_MCP_SPEC_TIMEOUT seconds and exiting non-zero if Arcane never answers (Docker restarts it).

2. Operations whose tag is in ARCANE_MCP_TAGS become tools named after their operationId in snake_case (list_containers, start_container, list_environments, ...). Streaming and binary-download endpoints are always excluded.

3. Every tool call is proxied to Arcane with your X-API-Key.

Most tools take an environment id. The local Docker host is "0"; remote agents have UUIDs (list_environments).

Safety

Destructive operations (any DELETE, plus paths ending in prune, destroy, kill, down, restore, restore-files) do not execute on the first call. They return:

{"requires_confirmation": true, "token": "3f9a...", "expires_in": 120, "operation": "delete_container", "arguments": {}}

The client must then call confirm_operation(token). Tokens are single-use and expire after 120 seconds. Disable with ARCANE_MCP_CONFIRM_DESTRUCTIVE=false; add patterns with ARCANE_MCP_DESTRUCTIVE_PATTERNS.

Configuration

With the default tags, Arcane 2.12 yields 137 generated tools plus confirm_operation.

Available tags in Arcane 2.12: Containers, Images, Volumes, Networks, Projects, Project Workspace, Environments, System, Dashboard, Activities, Events, Ports, Updater, Image Updates, Vulnerabilities, Health, Version, Swarm, GitOps Syncs, Templates, Volume Backup, Volume Workspace, Builds, Container Registries, Notifications, Webhooks, Customize, Users, Roles, API Keys, Auth, OIDC, Passkeys, MFA, Settings, System Backups, S3 Destinations, Federated Credentials, Variables, Diagnostics, JobSchedules, Jobs, Uploads, Mobile Push, Application Images, Stream.

Security notes

Intended for a LAN or an internal Docker network. If you expose it publicly, put TLS in front of it, keep the confirmation gate on, and consider ARCANE_MCP_READ_ONLY=true or a narrower tag list. GET /health is unauthenticated and reports only the tool count and Arcane URL.

Development

uv sync --extra dev
uv run pytest -q

Tests run against a committed snapshot of the Arcane 2.12.0 spec in tests/fixtures/openapi.json with a mocked Arcane backend.

Credits

Inspired by MikeCase/arcane-mcp, a hand-curated stdio server. This project instead generates tools from the OpenAPI spec and adds HTTP transport, auth and Docker packaging. MIT licensed.