randomsynergy17/arcane-mcp-server

21 stars 0 forks Quality 60 Trend 31

A comprehensive Model Context Protocol server that exposes the Arcane Docker Management API to AI assistants like Claude.

Overview

Manage your entire Docker infrastructure through natural language. 180 tools. One MCP server. Zero context switching. Getting Started • Tool Filtering • What Can It Do • Companion Skill • All Tools • Interactive Installer This is an independent, community-built project. It is the Arcane project or its maintainers. We build on top of Arcane's public API. Check out Portainer-Offload-Arcane — a guided migration wizard that moves your stacks, containers, volumes, registries, and users from Portainer CE/EE into Arcane. Run it once, then come back here to manage everything via natural language. Arcane MCP Server is a complete AI-powered Docker management bundle — an , a , and a , all in one package. - The gives your AI assistant 180 tools to control your Arcane Docker platform — containers, images, stacks, Swarm clusters, security scans, and more. Filter that set down to a preset (see Tool Filtering) if all 180 is more than your context window can spare.

README

Arcane MCP Server

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

Getting Started • Tool Filtering • 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.

Coming from Portainer? Check out Portainer-Offload-Arcane — a guided migration wizard that moves your stacks, containers, volumes, registries, and users from Portainer CE/EE into Arcane. Run it once, then come back here to manage everything via natural language.

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. Filter that set down to a preset (see Tool Filtering) if all 180 is more than your context window can spare.
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.

🆕 Recent update — v2.1: Tool filtering is here. All 180 tools in one turn eats your context window, so you can now pick a preset and ship only what you need. Details below.

Tool Filtering

Exposing all 180 tools to Claude every turn chews through your context window. Pick a preset to trim the active tool set — only the tools in that preset appear in tools/list:

Preset	Scope	Tools
`commonly-used` (recommended)	containers, images, projects, volumes, networks	~52
`read-only`	every `_list` / `_get` / `_inspect` / `_stats` across all modules	~60
`minimal`	dashboard + container list / get / counts	5
`deploy`	projects, gitops, templates, registries, environments, build	~40
`full` (default if never configured)	everything	180
`custom`	your own module + per-tool picks	variable

Configure interactively in Claude Code:

/arcane:configure

Walks you through picking a preset (and optional fine-tuning), shows a +X / −Y diff against what’s currently live, and writes the selection to ~/.arcane/config.json. The server watches that file — changes apply live via notifications/tools/list_changed, no reconnect.

Or set it by env var:

ARCANE_TOOL_PRESET=commonly-used
ARCANE_ENABLED_MODULES=container,image,dashboard
ARCANE_ENABLED_TOOLS=arcane_system_get_health
ARCANE_DISABLED_TOOLS=arcane_system_prune

Resolution order: preset → intersect with modules → add enabled → subtract disabled. Unknown names log a warning and are ignored — never silent failures, never a bricked server.

Non-Claude-Code clients can use the arcane_configure_tools MCP prompt for the same flow.

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.

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 five 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
`arcane_configure_tools`	Walks through selecting a tool-filter preset + module / per-tool overrides and writing them to `~/.arcane/config.json` (for clients without slash commands)

Plus four 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
`arcane://tools`	JSON inventory of every tool (name, module, enabled state) — consumed by `/arcane:configure` to compute the before/after diff
`arcane://tools-config-notice`	Flags installs that haven’t configured tool filtering yet and points them at `/arcane:configure`

And a Claude Code slash command:

Command	What it does
`/arcane:configure`	Interactive tool-filter picker — preset, module allowlist, per-tool overrides, with a live diff before writing

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

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`
`ARCANE_TOOL_PRESET`	`commonly-used` / `read-only` / `minimal` / `deploy` / `full` / `custom` — see Tool Filtering	-
`ARCANE_ENABLED_MODULES`	Comma-separated module allowlist	-
`ARCANE_ENABLED_TOOLS`	Comma-separated tool names to force-enable	-
`ARCANE_DISABLED_TOOLS`	Comma-separated tool names to force-disable	-
`LOG_LEVEL`	`debug`, `info`, `warn`, or `error`	`info`

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

Tool filter: anything set via env var overrides the corresponding field in ~/.arcane/config.json. Unset fields fall through to the file. Change at runtime by editing ~/.arcane/config.json — the server hot-reloads.

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             # 119 tests (unit + integration)
npm run dev          # stdio mode
npm run dev:tcp      # HTTP mode

Contributing

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

License

MIT License - see LICENSE for details.

Install

npx @randomsynergy/arcane-mcp-server

New to MCP? Start with the mcpskill.org guide →

Configuration

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

randomsynergy17/arcane-mcp-server

Overview

README

What is this?

Why use it?

Tool Filtering

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

Install

Configuration