Arcane Docker MCP Server

A Model Context Protocol (MCP) server for managing Docker environments through Arcane, deployed on Cloudflare Workers.

This MCP server provides Claude Desktop and other MCP clients with tools to manage Docker containers, images, volumes, networks, and Docker Compose stacks via Arcane's REST API.

What This Project Is

Arcane is a Docker management platform that provides a unified API for managing multiple Docker environments. This MCP server exposes Arcane's functionality as MCP tools, allowing you to interact with your Docker infrastructure through natural language conversations with Claude.

Built on Cloudflare Workers using the official Cloudflare agents package, this server provides a scalable, globally distributed way to manage your Docker resources.

Related MCP server: mcp-server-docker

Available Tools

Note: For tools that accept both *Id and *Name parameters (e.g., environmentId vs environmentName), you only need to provide one. The server will automatically resolve names to IDs via API calls.

Local Development Setup

Prerequisites

• Bun runtime

• An Arcane instance running on port 3552 (or any accessible port)

• An Arcane API key

Setup Steps

1. Clone the repository

git clone https://github.com/your-username/arcane-mcp-server.git
cd arcane-mcp-server

2. Install dependencies

bun install

3. Configure local secrets

Copy the example environment file and fill in your values:

cp .dev.vars.example .dev.vars

Edit .dev.vars with your Arcane API key:

ARCANE_API_KEY=your-api-key-here

4. Start the dev server

bun run dev

The server will start on http://localhost:8788.

5. Connect with MCP Inspector

In a second terminal:

bunx @modelcontextprotocol/inspector@latest

Connect the inspector to http://localhost:8788/mcp to verify:

• All tools appear under List Tools

• arcane_environment_list returns real data from your Arcane instance

• arcane_stack_list with environmentName (not ID) works via name resolution

• arcane_container_logs returns log content

• Invalid tool inputs return proper error responses

Connecting Claude Desktop via mcp-remote

To use this MCP server with Claude Desktop, configure it in your Claude Desktop settings:

1. Install the mcp-remote client if you haven't already:

bunx @modelcontextprotocol/inspector@latest

2. Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "arcane": {
      "command": "bunx",
      "args": ["mcp-remote", "https://arcane-mcp-server.<account>.workers.dev/mcp"]
    }
  }
}

Replace <account> with your Cloudflare account identifier.

Connecting OpenCode

To use this MCP server with OpenCode, configure it in your OpenCode settings:

1. Open OpenCode Settings → MCP Servers

2. Add a new MCP server with the following configuration:

{
  "name": "Arcane",
  "url": "https://arcane-mcp-server.<account>.workers.dev/mcp",
  "transport": "sse"
}

Replace <account> with your Cloudflare account identifier.

OpenCode Usage Examples

Once connected, you can interact with your Arcane Docker infrastructure through natural language conversations in OpenCode:

Example 1: List environments

User: Show me all my Docker environments
OpenCode: [Calls arcane_environment_list]
Here are your Docker environments:
- production (connected)
- staging (connected)
- dev (connected)

Example 2: Deploy a stack using a template

User: Deploy a WordPress stack to my production environment
OpenCode: [Calls arcane_template_list, then arcane_stack_deploy]
Deploying WordPress to production...
Stack 'wordpress' deployed successfully in environment 'production'

Example 3: Start/stop containers

User: Stop the database container in staging
OpenCode: [Calls arcane_environment_list, arcane_container_list, then arcane_container_stop]
Container 'db' stopped successfully in environment 'staging'

Example 4: Pull and prune images

User: Pull the latest nginx image and clean up unused images
OpenCode: [Calls arcane_image_pull, then arcane_image_prune]
Pulled nginx:latest...
Pruned 3 unused images, reclaimed 1.2GB

Example 5: Inspect a volume

User: Show me details of the data volume
OpenCode: [Calls arcane_volume_inspect]
Volume 'data' details:
- Driver: local
- Mountpoint: /var/lib/docker/volumes/data
- Created: 2024-01-15T10:30:00Z
- Size: 5.2GB

Secrets Setup

Secrets are managed through the Cloudflare Dashboard:

1. Navigate to Cloudflare Dashboard → Workers & Pages

2. Select your arcane-mcp-server worker

3. Go to Settings → Variables and Secrets

4. Add the following secret (type: Secret):

The Arcane host and port are configured via the Cloudflare VPC service binding (service_id in wrangler.jsonc) and do not need to be set here.

Deployment via Cloudflare Workers Builds

This project uses Cloudflare Workers Builds for continuous deployment from Git.

Initial Setup

1. Connect your repository

   Cloudflare Dashboard → Workers & Pages → Create application → Import a repository → select your GitHub repo.

2. Configure build settings

   • Build command: bun run type-check

   • Deploy command: bunx wrangler deploy

3. Set secrets

   Follow the Secrets Setup instructions above.

4. Verify Worker name

   The name in wrangler.jsonc must exactly match the Worker name in the Cloudflare dashboard. If there's a mismatch, the build will fail.

Deploying

Simply push to your main branch:

git push origin main

Monitor the build: Dashboard → Workers & Pages → your worker → Builds → View build history.

Running Tests

Run the test suite:

bun test

Run tests in watch mode:

bun run test:watch

All tests must pass before pushing to the repository.

Architecture

This project follows the Cloudflare agents package pattern:

• ArcaneAgent (Durable Object): Manages MCP sessions using WebSocket hibernation

• ArcaneClient: Typed HTTP client for the Arcane REST API

• Tool Registrations: MCP tools organized by domain (environments, stacks, containers, etc.)

• Name Resolution: Automatic resolution of resource names to IDs for user-friendly interactions

The Durable Object pattern is required by the agents package and handles:

• WebSocket session management

• Session state persistence

• Both SSE and Streamable HTTP transports automatically

• Cold starts and reconnections seamlessly

License

See LICENSE file for details.