Arcane Docker 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.

Available Tools

Tool Name	Description	Required Inputs
arcane_environment_list	List all Docker environments managed by Arcane	search?, limit?
arcane_environment_get	Get details of a specific environment	environmentId?, environmentName?
arcane_environment_create	Create a new Docker environment	name, apiUrl, accessToken?, enabled?, isEdge?
arcane_environment_update	Update an existing environment	environmentId?/environmentName?, name?, apiUrl?, etc.
arcane_environment_delete	Delete a Docker environment	environmentId?/environmentName?
arcane_stack_list	List Docker Compose stacks in an environment	environmentId?/environmentName?, search?
arcane_stack_get	Get details of a specific stack	environmentId?/environmentName?, stackId?/stackName?
arcane_stack_deploy	Deploy a new Docker Compose stack	environmentId?/environmentName?, name, composeContent
arcane_stack_update	Update an existing stack	environmentId?/environmentName?, stackId?/stackName?
arcane_stack_start	Start a Docker Compose stack	environmentId?/environmentName?, stackId?/stackName?
arcane_stack_stop	Stop a Docker Compose stack	environmentId?/environmentName?, stackId?/stackName?
arcane_stack_restart	Restart a Docker Compose stack	environmentId?/environmentName?, stackId?/stackName?
arcane_stack_pull	Pull images for a stack	environmentId?/environmentName?, stackId?/stackName?
arcane_stack_delete	Delete a Docker Compose stack	environmentId?/environmentName?, stackId?/stackName?
arcane_container_list	List all containers in an environment	environmentId?/environmentName?
arcane_container_get	Get details of a specific container	environmentId?/environmentName?, containerId?/containerName?
arcane_container_start	Start a container	environmentId?/environmentName?, containerId?/containerName?
arcane_container_stop	Stop a container	environmentId?/environmentName?, containerId?/containerName?
arcane_container_restart	Restart a container	environmentId?/environmentName?, containerId?/containerName?
arcane_container_kill	Force kill a container	environmentId?/environmentName?, containerId?/containerName?
arcane_image_list	List all Docker images in an environment	environmentId?/environmentName?
arcane_image_pull	Pull a Docker image	environmentId?/environmentName?, imageName
arcane_image_remove	Remove a Docker image	environmentId?/environmentName?, imageId
arcane_image_prune	Remove unused Docker images	environmentId?/environmentName?
arcane_volume_list	List all Docker volumes in an environment	environmentId?/environmentName?
arcane_volume_inspect	Get details of a specific volume	environmentId?/environmentName?, volumeName
arcane_volume_remove	Remove a Docker volume	environmentId?/environmentName?, volumeName
arcane_volume_prune	Remove unused Docker volumes	environmentId?/environmentName?
arcane_network_list	List all Docker networks in an environment	environmentId?/environmentName?
arcane_network_inspect	Get details of a specific network	environmentId?/environmentName?, networkId
arcane_network_remove	Remove a Docker network	environmentId?/environmentName?, networkId
arcane_network_prune	Remove unused Docker networks	environmentId?/environmentName?
arcane_template_list	List all Docker Compose templates	search?, limit?
arcane_template_get	Get details of a specific template	templateId
arcane_template_create	Create a new template	name, composeContent, description?, etc.
arcane_template_update	Update an existing template	templateId, name?, composeContent?, etc.
arcane_template_delete	Delete a template	templateId
arcane_version	Get the Arcane server version	-

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):

Name	Description
ARCANE_API_KEY	Your Arcane API key

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.