XenMCP Docker agent MCP server
Commit Nov 10, 2026Provides read-only access to Docker host information, container stats, logs, and events for AI clients.
Also known as xenMCP/docker-agent, docker-agent
- Stars
- 4
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 1.0.1
- Last commit
- Nov 10, 2026
- License
- MIT
What is XenMCP Docker agent MCP?
XenMCP Docker agent provides read-only access to Docker host information, container stats, logs, and events for AI clients.
Summary generated from the project's README
About XenMCP Docker agent MCP server
Monitoring Docker environments from within AI clients like Claude, Cursor, or VS Code is possible with this read-only agent. It provides a secure way for developers to inspect container states, resource usage, and system logs without risking accidental changes to the host. The server can be deployed locally using stdio or remotely via HTTP behind a reverse proxy like Caddy, Nginx, or Traefik.
Users can access specific data through tools such as docker_info for system specifications, list_containers for active workloads, and container_stats for real-time CPU and memory metrics. It also includes container_logs for searching stdout or stderr and recent_events to track lifecycle changes like restarts or OOM kills. To ensure security, the agent uses a strict allow-list of GET requests and never exposes environment variables or command arguments.
When used with the XenMCP platform, the agent supports individual OAuth sign-ins and maintains a full call journal. For local setups, it connects directly to the Docker socket via a read-only mount, ensuring that the AI can see but never start, stop, or remove any containers.
What you can do with it
- 1Troubleshoot container crashesAsk the AI to find out why a container recently stopped by checking exit codes and recent events.
- 2Analyze real-time resource usageRequest a summary of current CPU and memory consumption across all running containers.
- 3Audit host system specificationsGet a high-level overview of the Docker host including OS, CPU count, and total memory.
Written from the project's README. Every use case is checked against a quote from it.
How to install XenMCP Docker agent MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall XenMCP Docker agent MCP in Claude Code
$ claude mcp add --env 'XENMCP_AGENT_KEY=<YOUR_XENMCP_AGENT_KEY>' docker-agent -- docker run -i --rm ghcr.io/xenmcp/docker-agent:1.0.1Install XenMCP Docker agent MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"docker-agent": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/xenmcp/docker-agent:1.0.1"
],
"env": {
"XENMCP_AGENT_KEY": "<YOUR_XENMCP_AGENT_KEY>"
}
}
}
}Install XenMCP Docker agent MCP in VS Code
.vscode/mcp.json
{
"servers": {
"docker-agent": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/xenmcp/docker-agent:1.0.1"
],
"env": {
"XENMCP_AGENT_KEY": "<YOUR_XENMCP_AGENT_KEY>"
}
}
}
}Install XenMCP Docker agent MCP in VS Code CLI
$ code --add-mcp '{"name":"docker-agent","type":"stdio","command":"docker","args":["run","-i","--rm","ghcr.io/xenmcp/docker-agent:1.0.1"],"env":{"XENMCP_AGENT_KEY":"<YOUR_XENMCP_AGENT_KEY>"}}'Install XenMCP Docker agent MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"docker-agent": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/xenmcp/docker-agent:1.0.1"
],
"env": {
"XENMCP_AGENT_KEY": "<YOUR_XENMCP_AGENT_KEY>"
}
}
}
}Install XenMCP Docker agent MCP in Codex
$ codex mcp add docker-agent --env 'XENMCP_AGENT_KEY=<YOUR_XENMCP_AGENT_KEY>' -- docker run -i --rm ghcr.io/xenmcp/docker-agent:1.0.1Install XenMCP Docker agent MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.docker-agent] command = "docker" args = ["run", "-i", "--rm", "ghcr.io/xenmcp/docker-agent:1.0.1"] [mcp_servers.docker-agent.env] XENMCP_AGENT_KEY = "<YOUR_XENMCP_AGENT_KEY>"
Install XenMCP Docker agent MCP in Gemini CLI
$ gemini mcp add -s user -e 'XENMCP_AGENT_KEY=<YOUR_XENMCP_AGENT_KEY>' docker-agent docker -- run -i --rm ghcr.io/xenmcp/docker-agent:1.0.1Install XenMCP Docker agent MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"docker-agent": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/xenmcp/docker-agent:1.0.1"
],
"env": {
"XENMCP_AGENT_KEY": "<YOUR_XENMCP_AGENT_KEY>"
}
}
}
}Needs a key before it starts
Started on 16 Nov 2026 with no keys, it stopped and asked for one, so a client sees no tools until you set the variables above.
Configuration
XENMCP_AGENT_KEYRequiredSecretKey callers must send as Authorization: Bearer (at least 32 characters)
XENMCP_ALLOW_IPSAddresses or CIDRs allowed to call the agent, comma-separated (default: XenMCP's address)
Automated checks
Ran Nov 12, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packageNot checked
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesNot checked
README
View on GitHubXenMCP Docker agent
A small, read-only MCP server for the containers on one Docker host. Run it next to your containers, put it behind your reverse proxy, and connect it to Claude, Cursor or VS Code through XenMCP: every person signs in on their own (OAuth), access can be revoked at any time, and every call is in the journal.
It can see, never change:
| Tool | What it does |
|---|---|
docker_info |
Docker version, OS, CPUs, memory, number of containers and images |
list_containers |
Name, image, state, uptime, ports, compose project |
inspect_container |
State, exit code, OOM kill, restarts, health check, limits, log driver, mounts, networks — never environment variables or command arguments |
container_logs |
Last lines, a time window (since / until: 15m, 6h, 2d or an ISO time), stdout or stderr only, text or regex search; at most 500 lines per call |
container_stats |
CPU, memory, network, processes right now |
recent_events |
start, stop, die (with exit code), kill, OOM, restart, health status — up to 7 days |
There is no tool that starts, stops, restarts, removes, execs, builds or pulls. The agent sends Docker only a short list of GET requests (lib.mjs, allowedPath) and refuses everything else before it leaves the process.
Install
- In the XenMCP panel: Add server → Docker agent. It shows a key and the command below with the key filled in.
- On your Docker host:
docker run -d --name xenmcp-docker-agent --restart unless-stopped \
--read-only --cap-drop ALL --security-opt no-new-privileges --memory 128m \
--group-add "$(stat -c %g /var/run/docker.sock)" \
-v /var/run/docker.sock:/var/run/docker.sock:ro \
-e XENMCP_AGENT_KEY=<the key from the panel> \
-p 127.0.0.1:8090:8080 \
ghcr.io/xenmcp/docker-agent:1.0
- Make it reachable over HTTPS through your reverse proxy (below), e.g.
https://docker-agent.example.com/mcp. - In the panel: enter that address and press Check and save.
Or with Docker Compose:
services:
xenmcp-docker-agent:
image: ghcr.io/xenmcp/docker-agent:1.0
restart: unless-stopped
read_only: true
cap_drop: [ALL]
security_opt: [no-new-privileges:true]
mem_limit: 128m
group_add: ["${DOCKER_GID}"] # stat -c %g /var/run/docker.sock
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
environment:
XENMCP_AGENT_KEY: ${XENMCP_AGENT_KEY}
ports:
- 127.0.0.1:8090:8080
Reverse proxy
The agent listens on plain HTTP; your proxy adds HTTPS. It must pass X-Forwarded-For (all three below do).
Caddy
docker-agent.example.com {
reverse_proxy 127.0.0.1:8090
}
nginx
server {
listen 443 ssl;
server_name docker-agent.example.com;
# ssl_certificate …; ssl_certificate_key …;
location /mcp {
allow 46.225.57.217; # XenMCP
deny all;
proxy_pass http://127.0.0.1:8090;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_buffering off;
proxy_read_timeout 120s;
}
}
Traefik (labels on the agent container, without ports)
labels:
- traefik.enable=true
- traefik.http.routers.xenmcp-agent.rule=Host(`docker-agent.example.com`) && PathPrefix(`/mcp`)
- traefik.http.routers.xenmcp-agent.tls.certresolver=letsencrypt
- traefik.http.services.xenmcp-agent.loadbalancer.server.port=8080
Without XenMCP
The agent is a plain MCP server (Streamable HTTP at /mcp), so any client that can send a header works. Set XENMCP_ALLOW_IPS to the addresses that may call it (* for any, only behind your own proxy or firewall) and send the key as Authorization: Bearer <key>. Without XenMCP there is no per-person sign-in and no journal: everyone with the key has the same access.
Over stdio, for a local client
Started with --stdio, the agent talks MCP over stdin/stdout instead of HTTP: no key, no port, no address list – whoever starts it already has the Docker socket. For Claude Desktop, Cursor or VS Code on the Docker host itself:
{
"mcpServers": {
"docker": {
"command": "docker",
"args": ["run", "-i", "--rm", "--no-healthcheck", "--read-only", "--cap-drop", "ALL", "--security-opt", "no-new-privileges",
"--group-add", "<stat -c %g /var/run/docker.sock>",
"-v", "/var/run/docker.sock:/var/run/docker.sock:ro",
"ghcr.io/xenmcp/docker-agent:1.0", "node", "server.mjs", "--stdio"]
}
}
}
Or from a checkout: node server.mjs --stdio. The same six read-only tools; XENMCP_CONTAINERS and the xenmcp.hide label apply.
It is listed in the official MCP Registry as com.xenmcp/docker-agent (server.json in this repository).
Settings
| Variable | Default | |
|---|---|---|
XENMCP_AGENT_KEY |
— | Required over HTTP, at least 32 characters; XenMCP sends it as Authorization: Bearer. Not used with --stdio. |
XENMCP_ALLOW_IPS |
46.225.57.217 |
Who may call, comma-separated, CIDR allowed. Behind a proxy on a private address the last X-Forwarded-For entry counts. |
XENMCP_CONTAINERS |
all | Only these containers, comma-separated, * as wildcard (e.g. shop-*,nginx). |
XENMCP_MAX_SCAN_MB |
200 |
How much log one search or stream filter reads at most. |
PORT |
8080 |
Hide single containers with the label xenmcp.hide=true: they are left out of every answer.
Good to know
- Logs are what Docker keeps: with the default
json-filedriver everything since the container was created, unless you setmax-size/max-file. A recreated container starts with an empty log. For history beyond that, use Grafana + Loki. - Logs can contain personal data and secrets. What a tool returns goes to the AI client you connect (for Claude: Anthropic). Hide containers you do not want to share.
- The socket is mounted read-only, but Docker's API does not know read-only mounts — the limit is the agent's own allow-list, which is why it is small, open source and tested (
npm test,npm run e2e).
Develop
npm ci
npm test # unit tests and stdio (no Docker needed)
npm run e2e # against your local Docker (starts and removes three busybox containers)
Questions and feedback
Ask in the XenMCP community on Discord (forum #help, tag docker-agent) or open an issue here. Security issues: security@xenmcp.com, not in public.
XenMCP Docker agent MCP questions
How do I add XenMCP Docker agent MCP to Claude Code?
Run claude mcp add --env 'XENMCP_AGENT_KEY=<YOUR_XENMCP_AGENT_KEY>' docker-agent -- docker run -i --rm ghcr.io/xenmcp/docker-agent:1.0.1 in your terminal. Add --scope user to make it available in every project.
How do I add XenMCP Docker agent MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Does the server expose sensitive environment variables?
No, the inspect tool is designed to never reveal environment variables or command arguments.