swarmexec

swarmexec › Docs › MCP server for AI assistants

MCP server for AI assistants_

Swarm access for an AI assistant, per service, by label — read-only except for an opt-in command.

mcp — let an AI assistant inspect the swarm

swarmexec mcp is a Model Context Protocol server on stdin/stdout. An AI assistant such as Claude Code can then look at the swarm through the same two channels every other command uses — the manager API and the node agents — on any Docker context, ssh:// included. It reads status, tasks, logs and resource usage, diffs and checks stack files, and, where you allow it, runs a single non-interactive command in a container. Apart from that one tool (exec_run, off unless a service's labels allow it, and a command can of course change whatever it can reach) it changes nothing.

claude mcp add swarmexec -- swarmexec mcp

Every tool takes an optional context argument; without it the server uses the context it was started with (--context, DOCKER_CONTEXT, DOCKER_HOST, docker's current context). Connections are kept per context for the session, as the TUI does on a context switch.

Only the contexts you allow. The assistant gets the context the server was started with, plus those named with --contexts — nothing else. Every other context on the workstation, production included, does not exist for it: contexts_list leaves it out, name and address, and naming it answers unknown docker context, exactly like a name that does not exist.

swarmexec mcp --context staging --contexts lab,test
ToolAnswersNeeds
contexts_listthe Docker contexts the assistant may use (see --contexts), and which one the server uses—
cluster_overviewnodes, and replica and health state of the visible services — on the command line status—
services_listlike ps: mode, replicas, image, ports, stack and running containersenable
service_inspectone service's configuration and its recent tasksenable
logs_readrecent logs: tail, since, regexp and minimum level, capped; never follows; when every stream fails the call is an error result (isError), when only some do the lines that arrived come back with a notelogs
statslive CPU, memory and healthcheck state per container; waits a few seconds for an agent that has not been asked for a while — on the command line statsenable
volumes_list / networks_list / secrets_list / configs_listnames only, and only those the visible services use; networks_list adds each network's subnets and the subnet overlap findings (node IPs inside — as a count, underlay or network overlap — another network named only if visible) with the fix; with endpoints: true it also asks every node's agent (network.inspect) and adds per node the running tasks, local containers, load-balancer endpoints, MACs and networkdb entries, plus stale address candidates and duplicates — all counted over the visible services only: a hidden service's tasks and endpoints count nowhere and never show up as stale or duplicate, a leftover of a removed service is listed without its name; node hostnames only, never node addressesenable
stack_diff / stack_checkwhat deploying a stack file would change / what the deploy check finds — nothing is deployed; on the command line stack diff / stack checkenable on every service of the file
security_reportthe security report, limited to the visible services and what they use--allow report
doctormanager and agent health, as doctor—
exec_runone command, no TTY, no stdin, with a timeout (timeout_seconds, default 30, at most 300; a command still running then comes back as “the command did not finish within …”) and an output capexec

Access: service labels

What the assistant may see is decided per service by service labels — in a compose file, deploy.labels, the way Traefik is configured in Swarm mode. Nothing is visible by default.

# compose file: deploy.labels, not the container labels services: api: image: registry.example.com/api:1.4 deploy: labels: swarmexec.mcp.enable: "true" # the service exists for the assistant swarmexec.mcp.logs: "true" # it may read the logs swarmexec.mcp.exec: "true" # it may run a command in a container
FlagDefaultDescription
--defaultnoneaccess for services without swarmexec.mcp.enable: none or list (read is accepted for list)
--allow—optional tools: report adds security_report
--connect-timeout10stimeout for connecting to an agent
--contexts—further Docker contexts the assistant may use, besides the one the server starts with; a comma list or repeated. A name that is not a context fails at startup

Security notes