GitHub - RandomSynergy17/Arcane-MCP-Server: A comprehensive Model Context Protocol server that exposes the Arcane Docker Management API to AI assistants like Claude. 165+ tools covering containers, images, volumes, networks, Docker Compose stacks, Swarm clusters, vulnerability scanning, GitOps, and more.

Arcane MCP Server

Manage your entire Docker infrastructure through natural language.
180 tools. One MCP server. Zero context switching.

Getting Started • What Can It Do • Companion Skill • All Tools • Interactive Installer

Note: This is an independent, community-built project. It is not affiliated with, endorsed by, or maintained by the Arcane project or its maintainers. We build on top of Arcane's public API.

What is this?

Arcane MCP Server is a complete AI-powered Docker management bundle — an MCP server, a Claude Code plugin, and a companion skill, all in one package.

The MCP server gives your AI assistant 180 tools to control your Arcane Docker platform — containers, images, stacks, Swarm clusters, security scans, and more.
The plugin wraps everything into a single install with guided configuration — no manual env vars or config files.
The companion skill teaches your AI how to use those tools — safe deployment workflows, troubleshooting patterns, and guardrails so it doesn't accidentally nuke your volumes.

Instead of clicking through dashboards and running CLI commands, you just talk to your infrastructure:

"What's running on production?"

"Deploy this compose file to staging."

"Are any images vulnerable? Show me the critical ones."

"Scale the API service to 5 replicas."

Behind the scenes, the server translates your requests into the right API calls — with safety checks, retry logic, and formatted responses that actually make sense.

Why use it?

	Without	With Arcane MCP Server
Check container status	Open dashboard, navigate to environment, filter, scroll	"What's broken?"
Deploy a stack	Write compose, scp to server, ssh, docker compose up	"Deploy this compose file"
Find vulnerabilities	Configure Trivy, run scan, parse JSON output	"Run a security audit"
Update containers	Check each image, pull, recreate, verify	"Update everything" (dry-run first, obviously)
Clean up disk space	Prune images, volumes, networks one by one	"Clean up unused resources"

Every tool carries safety annotations so your AI knows which operations are read-only and which ones need confirmation before running. No accidental docker system prune moments.

Getting Started

The fastest way — paste this into Claude Code:

Fetch and follow: https://raw.githubusercontent.com/RandomSynergy17/Arcane-MCP-Server/main/install_arcane_skill-mcp.md

It'll walk you through setup interactively. Or pick your preferred method below.

npm Install

npm install -g @randomsynergy/arcane-mcp-server

Claude Code Plugin (recommended)

/plugin marketplace add RandomSynergy17/Arcane-MCP-Server
/plugin install arcane-mcp-server

You'll be prompted for your Arcane URL and API key during setup. That's it — MCP server and companion skill installed together.

Claude Code (manual)

claude mcp add --transport stdio \
  --env ARCANE_API_KEY=your-key \
  --env ARCANE_BASE_URL=https://arcane.example.com:3552 \
  arcane -- npx @randomsynergy/arcane-mcp-server

Claude Desktop

Add to ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "arcane": {
      "command": "npx",
      "args": ["@randomsynergy/arcane-mcp-server"],
      "env": {
        "ARCANE_BASE_URL": "https://arcane.example.com:3552",
        "ARCANE_API_KEY": "your-api-key"
      }
    }
  }
}

HTTP / Network Mode

For remote or multi-client access:

ARCANE_API_KEY=your-key npx @randomsynergy/arcane-mcp-server --tcp

Connect at http://localhost:3000/mcp. Set ARCANE_HTTP_PORT to change the port.

Config File

Create ~/.arcane/config.json:

{
  "baseUrl": "https://arcane.example.com:3552",
  "auth": { "type": "apikey", "apiKey": "your-api-key" }
}

Prerequisites

You need an Arcane instance running (see getarcane.app) and an API key from Settings > API Keys.

What Can It Do?

Containers & Compose

Deploy, start, stop, restart, redeploy, and monitor Docker containers and Compose stacks. Inspect details, check ports, toggle auto-updates — all through conversation.

Docker Swarm

Full cluster management. Initialize clusters, join nodes, deploy services, scale replicas, view logs, and manage the entire swarm lifecycle.

Security & Vulnerability Scanning

Scan images for CVEs, get severity breakdowns, track which images need attention, and ignore known false positives. Environment-wide security summaries in one call.

GitOps & Deployments

Connect Git repositories, set up automated sync, and deploy directly from branches. Supports folder-level sync and auto-deploy on push.

Image Builds & Updates

Build images from Dockerfiles or Git URLs, check all running containers for available updates, and roll out updates with dry-run support.

Infrastructure Management

Manage volumes (browse files, create backups, restore), networks (create, inspect topology), and registries (Docker Hub, GHCR, ECR, GCR, ACR).

Operations Dashboard

Get a consolidated snapshot of your entire environment in one call — container counts, project status, available updates, action items that need attention.

The Companion Skill

The MCP server gives Claude the tools. The companion skill gives it the knowledge — how to use those tools effectively, safely, and in the right order.

Install with the plugin (automatic) or manually:

git clone --depth 1 https://github.com/RandomSynergy17/Arcane-MCP-Server.git /tmp/arcane
cp -r /tmp/arcane/skills/arcane-mcp-server ~/.claude/skills/arcane-mcp-server
rm -rf /tmp/arcane

What the skill teaches Claude:

Intent mapping — When you say "what's broken?", Claude knows to call arcane_dashboard_get + arcane_dashboard_get_action_items instead of listing every container one by one.

Safety guardrails — Before running arcane_volume_prune, Claude will suggest arcane_volume_backup_create first. Before arcane_updater_run, it'll do a dry run. Before arcane_project_destroy, it confirms twice.

Workflow chains — Multi-step operations like "deploy → pull images → start → verify" are sequenced correctly, not fired off randomly.

Gotchas — Things like "environmentId is required on almost every call", "ECR credentials expire", and "always use dryRun: true before running the auto-updater" are baked in so you don't learn them the hard way.

Built-in Workflow Prompts

The server includes four pre-built prompts that guide Claude through common multi-step operations:

Prompt	What it does
`/deploy-stack`	Walks through creating a project, pulling images, deploying, and verifying all services are healthy
`/troubleshoot-container`	Systematic diagnosis: check state, inspect config, review action items, check ports, scan for vulnerabilities
`/security-audit`	Full environment scan: check scanner status, get vulnerability summary, review all findings by severity, check for image updates
`/cleanup-environment`	Safe cleanup: survey resources, present a plan, get confirmation, then prune images, networks, and volumes in the right order

Plus two MCP Resources that give Claude background context:

Resource	What it provides
`arcane://environments`	All available environments with IDs and status — so Claude can pick the right one
`arcane://version`	Server configuration details — base URL, default environment, protocol version

All 180 Tools

Containers (11)

Tool	Description
`arcane_container_list`	List containers with filtering and pagination
`arcane_container_get`	Get detailed container information
`arcane_container_create`	Create a new container
`arcane_container_start`	Start a stopped container
`arcane_container_stop`	Stop a running container
`arcane_container_restart`	Restart a container
`arcane_container_update`	Pull latest image and recreate
`arcane_container_redeploy`	Redeploy a single container
`arcane_container_set_auto_update`	Toggle per-container auto-update
`arcane_container_delete`	Delete a container
`arcane_container_get_counts`	Get running/stopped counts

Docker Swarm (11)

Tool	Description
`arcane_swarm_list_services`	List swarm services
`arcane_swarm_get_service`	Get service details and tasks
`arcane_swarm_create_service`	Create a swarm service
`arcane_swarm_update_service`	Update service configuration
`arcane_swarm_delete_service`	Delete a swarm service
`arcane_swarm_scale_service`	Scale service replicas
`arcane_swarm_get_service_logs`	Get service logs
`arcane_swarm_init_cluster`	Initialize a new swarm cluster
`arcane_swarm_join_cluster`	Join an existing cluster
`arcane_swarm_leave_cluster`	Leave the swarm cluster
`arcane_swarm_get_cluster_info`	Get cluster info and node counts

Vulnerability Scanning (12)

Tool	Description
`arcane_vulnerability_scan_image`	Trigger a vulnerability scan
`arcane_vulnerability_get_scan_result`	Get full scan result
`arcane_vulnerability_get_scan_summary`	Get summary for an image
`arcane_vulnerability_get_scan_summaries`	Batch scan summaries
`arcane_vulnerability_list`	List vulnerabilities with filtering
`arcane_vulnerability_get_environment_summary`	Environment-wide summary
`arcane_vulnerability_ignore`	Ignore a vulnerability
`arcane_vulnerability_unignore`	Unignore a vulnerability
`arcane_vulnerability_get_scanner_status`	Get Trivy scanner status
`arcane_vulnerability_list_all`	List all vulns across environment
`arcane_vulnerability_list_ignored`	List ignored vulnerabilities
`arcane_vulnerability_get_image_options`	List scannable images

Projects / Docker Compose (12)

Tool	Description
`arcane_project_list`	List Docker Compose projects
`arcane_project_get`	Get project details
`arcane_project_create`	Create from compose YAML
`arcane_project_update`	Update project configuration
`arcane_project_up`	Deploy a project
`arcane_project_down`	Stop and remove containers
`arcane_project_restart`	Restart all services
`arcane_project_redeploy`	Redeploy (down + up)
`arcane_project_destroy`	Destroy project and volumes
`arcane_project_pull_images`	Pull latest images
`arcane_project_get_counts`	Get status counts
`arcane_project_build`	Build project images

Images, Builds & Updates (20 tools)

Tool	Description
`arcane_image_list`	List images
`arcane_image_get`	Get image details
`arcane_image_pull`	Pull from registry
`arcane_image_delete`	Remove an image
`arcane_image_prune`	Prune unused images
`arcane_image_get_counts`	Get image statistics
`arcane_image_check_update`	Check single image for updates
`arcane_image_check_updates_all`	Check all images
`arcane_image_get_update_summary`	Get update summary
`arcane_image_update_check`	Check update by reference
`arcane_image_update_check_by_id`	Check update by ID
`arcane_image_update_check_multiple`	Batch check
`arcane_image_update_check_all`	Check all for updates
`arcane_image_update_get_summary`	Get update summary
`arcane_build_image`	Build from Dockerfile or Git URL
`arcane_build_list`	List image builds
`arcane_build_get`	Get build details
`arcane_build_workspace_browse`	Browse workspace files
`arcane_build_workspace_content`	Read workspace file
`arcane_build_workspace_upload`	Upload to workspace

Volumes, Networks & Ports (22 tools)

Tool	Description
`arcane_volume_list`	List volumes
`arcane_volume_get`	Get volume details
`arcane_volume_create`	Create a volume
`arcane_volume_delete`	Delete a volume
`arcane_volume_prune`	Prune unused volumes
`arcane_volume_get_counts`	Get volume counts
`arcane_volume_browse`	Browse volume files
`arcane_volume_browse_content`	Read file content
`arcane_volume_browse_mkdir`	Create directory
`arcane_volume_backup_list`	List backups
`arcane_volume_backup_create`	Create backup
`arcane_volume_backup_delete`	Delete backup
`arcane_volume_backup_restore`	Restore from backup
`arcane_volume_backup_list_files`	List backup files
`arcane_network_list`	List networks
`arcane_network_get`	Get network details
`arcane_network_create`	Create a network
`arcane_network_delete`	Delete a network
`arcane_network_prune`	Prune unused networks
`arcane_network_get_counts`	Get network counts
`arcane_network_get_topology`	Get network topology graph
`arcane_port_list`	List all port mappings

GitOps, Webhooks, Auto-Updater & Dashboard (23 tools)

Tool	Description
`arcane_gitops_list`	List GitOps syncs
`arcane_gitops_get`	Get sync details
`arcane_gitops_create`	Create a sync
`arcane_gitops_update`	Update a sync
`arcane_gitops_delete`	Delete a sync
`arcane_gitops_sync`	Trigger sync
`arcane_gitops_get_status`	Get sync status
`arcane_git_repo_list`	List Git repositories
`arcane_git_repo_create`	Add a repository
`arcane_git_repo_test`	Test connectivity
`arcane_git_repo_get_branches`	List branches
`arcane_git_repo_browse_files`	Browse repo files
`arcane_git_repo_delete`	Delete repository
`arcane_webhook_list`	List webhooks
`arcane_webhook_create`	Create a webhook
`arcane_webhook_update`	Update a webhook
`arcane_webhook_delete`	Delete a webhook
`arcane_updater_run`	Run auto-updater (dry run supported)
`arcane_updater_update_container`	Update single container
`arcane_updater_get_status`	Get updater schedule
`arcane_updater_get_history`	Get update history
`arcane_dashboard_get`	Get dashboard snapshot
`arcane_dashboard_get_action_items`	Get action items

Environments, Registries, Auth & More (69 tools)

Category	Tools	What it covers
Environments	10	List, create, update, delete environments. Test connectivity, pair agents, get Docker info, deployment snippets
Container Registries	7	Docker Hub, GHCR, ECR, GCR, ACR. Create, update, delete, test, sync registries
Templates	8	Docker Compose templates with variables. Browse, create, download, manage
Jobs	4	Scheduled tasks. List jobs, get schedules, run on demand
Notifications	6	Alert configuration via Apprise. Get/set settings, test notifications
Events	4	Activity tracking. List events by environment, create, delete
Users	5	User management. List, create, update, delete users
Settings	8	Server configuration and API key management
Authentication	8	Login, logout, JWT token management, OIDC device flow
System	9	Health checks, Docker info, system prune, upgrade checks, start/stop all containers

Configuration

Variable	Description	Default
`ARCANE_BASE_URL`	Your Arcane instance URL	Required
`ARCANE_API_KEY`	API key for authentication	-
`ARCANE_USERNAME`	Username (alternative JWT auth)	-
`ARCANE_PASSWORD`	Password (alternative JWT auth)	-
`ARCANE_TIMEOUT_MS`	Request timeout in milliseconds	`30000`
`ARCANE_SKIP_SSL_VERIFY`	Skip SSL cert verification (self-signed certs)	`false`
`ARCANE_DEFAULT_ENVIRONMENT_ID`	Auto-select this environment	-
`ARCANE_HTTP_PORT`	Port for HTTP/network mode	`3000`
`ARCANE_HTTP_HOST`	Host for HTTP/network mode	`localhost`
`LOG_LEVEL`	`debug`, `info`, `warn`, or `error`	`info`

Authentication: API Key is recommended. JWT tokens are automatically refreshed before they expire.

Safety & Destructive Operations

Every tool includes MCP annotations that tell your AI assistant whether it's safe to run without asking. Read-only tools (list, get, browse) run freely. Destructive tools require confirmation.

Tool	Risk	What happens
`arcane_volume_delete`	CRITICAL	Permanently deletes a volume and its data
`arcane_volume_prune`	CRITICAL	Removes all unused volumes
`arcane_project_destroy`	CRITICAL	Destroys a project, optionally including volumes
`arcane_system_prune`	CRITICAL	Removes all unused containers, images, networks, volumes
`arcane_swarm_init_cluster`	CRITICAL	Converts a standalone node to a swarm manager
`arcane_swarm_leave_cluster`	CRITICAL	Disconnects from the swarm cluster
`arcane_container_delete`	HIGH	Deletes a container
`arcane_network_delete`	HIGH	Deletes a network
`arcane_image_prune`	HIGH	Removes unused images
`arcane_swarm_delete_service`	HIGH	Removes a swarm service

The companion skill adds an additional safety layer — it teaches Claude to back up before deleting, dry-run before updating, and always confirm before destroying.

Development

git clone https://github.com/RandomSynergy17/Arcane-MCP-Server.git
cd Arcane-MCP-Server
npm install
npm run build
npm test             # 79 tests
npm run dev          # stdio mode
npm run dev:tcp      # HTTP mode

Project Structure

src/
  index.ts              # stdio entry point
  tcp-server.ts         # HTTP/Streamable entry point (rate-limited)
  server.ts             # MCP server factory (tools + resources + prompts)
  config.ts             # Configuration (env vars > config file > defaults)
  client/
    arcane-client.ts    # HTTP client (retry, SSL, size limits)
  auth/
    auth-manager.ts     # JWT auto-refresh + API key auth
  tools/                # 25 modules, 180 tools
  resources/            # 2 MCP Resources
  prompts/              # 4 MCP Prompts
  types/
    arcane-types.ts     # Shared interfaces (33 types)
    generated/          # Auto-generated from OpenAPI v1.17.0
  utils/
    tool-helpers.ts     # registerTool wrapper with isError handling
    format.ts           # Size formatting + path validation
    error-handler.ts    # Error classes + formatting
skills/
  arcane-mcp-server/
    SKILL.md            # Companion Claude Code skill

Contributing

Contributions welcome! See CONTRIBUTING.md for setup instructions and guidelines.

License

MIT License - see LICENSE for details.

Links

Arcane — The Docker management platform this connects to
npm package — npx @randomsynergy/arcane-mcp-server
Interactive Installer — Guided setup for Claude Code
Model Context Protocol — The MCP specification
MCP TypeScript SDK — SDK used by this server

A RandomSynergy production

Name		Name	Last commit message	Last commit date
Latest commit History 65 Commits
.claude-plugin		.claude-plugin
.github		.github
_docs		_docs
assets		assets
scripts		scripts
skills/arcane-mcp-server		skills/arcane-mcp-server
src		src
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
.mcp.json		.mcp.json
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
install_arcane_skill-mcp.md		install_arcane_skill-mcp.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

Arcane MCP Server

What is this?

Why use it?

Getting Started

npm Install

Claude Code Plugin (recommended)

Prerequisites

What Can It Do?

Containers & Compose

Docker Swarm

Security & Vulnerability Scanning

GitOps & Deployments

Image Builds & Updates

Infrastructure Management

Operations Dashboard

The Companion Skill

What the skill teaches Claude:

Built-in Workflow Prompts

All 180 Tools

Containers (11)

Docker Swarm (11)

Vulnerability Scanning (12)

Projects / Docker Compose (12)

Configuration

Safety & Destructive Operations

Development

Contributing

License

Links

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 4

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages