mcp-docker-agentic

An MCP server for agentic Docker container operations. It uses the local docker binary, so authentication, networking, volumes, and context are whatever docker on your machine is configured for.

Concept

This is the Docker twin of mcp-ssh-agentic. Where the SSH server targets user@host[:port], this server targets a Docker container name or id. The tool names are parallel (ssh_* → docker_*) so existing muscle memory transfers across.

Running with npx

After release, the package is on npmjs and GitHub Packages as @jahrulnr/mcp-docker-agentic.

npmjs (simplest):

{
  "mcpServers": {
    "docker-agentic": {
      "command": "npx",
      "args": ["-y", "@jahrulnr/mcp-docker-agentic"]
    }
  }
}

GitHub Packages (needs a PAT with read:packages in ~/.npmrc):

@jahrulnr:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_PAT

{
  "mcpServers": {
    "docker-agentic": {
      "command": "npx",
      "args": ["-y", "--registry=https://npm.pkg.github.com", "@jahrulnr/mcp-docker-agentic"]
    }
  }
}

The container must already exist and be running. Pass the container name or id as container, for example my-app or a1b2c3d4.

Available Tools

docker_ping, docker_read_file, docker_write_file, docker_read_image, docker_list_dir, docker_mkdir, docker_grep, docker_apply_patch, docker_delete, docker_exec, docker_interactive_exec, docker_interactive_input, docker_interactive_close, docker_interactive_list, docker_cp_to, docker_cp_from, docker_close

Examples:

docker_ping("my-app")
docker_read_file("my-app", "/app/config.json")
docker_write_file("my-app", "/app/.env", "PORT=3000\n")
docker_mkdir("my-app", "/app/releases/42")
docker_list_dir("my-app", "/var/log")
docker_grep("my-app", "TODO", "/app", "*.js")
docker_exec("my-app", "ps aux")

# Commands that may require interactive input:
docker_interactive_exec("my-app", "apt-get upgrade")
docker_interactive_input(session_id="abc123", input="Y")
docker_interactive_close("abc123")

docker_cp_to("my-app", "./dist/app.tar.gz", "/app/app.tar.gz")
docker_cp_from("my-app", "/app/logs/app.log", "./app.log")

Behavior Notes

• docker_delete uses rm -f for files and rm -rf only when recursive=true.

• docker_write_file writes or overwrites a container file directly from text. Use append=true to append instead of overwrite. Parent directories are created automatically unless create_dirs=false.

• docker_mkdir is equivalent to mkdir -p inside the container.

• docker_exec has a default timeout of 30 seconds and a maximum output size of 5 MiB. docker_read_image supports files up to 20 MiB. docker_write_file accepts content up to 5 MiB. docker_cp_* operations default to a 120-second timeout.

• All container commands run inside a non-login, non-interactive shell (bash --noprofile --norc -c, falling back to sh -c) so broken profile scripts cannot corrupt output. docker_exec always returns exit_code=N along with stdout. If stderr is present, it is included in a [stderr] section. Non-zero exit codes set isError, but stdout is still returned.

• Interactive sessions (TTY): docker_interactive_exec runs docker exec -it, allocating a pseudo-terminal so programs that require a real terminal (sudo, passwd, confirmation prompts, setup wizards, REPLs) behave correctly. The server waits until output has been quiet for quiet_ms (default: 500 ms) or the process exits, then returns the collected output along with a session_id. Continue the session using docker_interactive_input (leave input empty to simply wait for more output without sending anything). This mechanism is based on output inactivity rather than prompt detection. Commands that continuously produce output may cause the tool call to wait longer. The server allows up to 8 concurrent interactive sessions, automatically cleans up sessions after 10 minutes of inactivity, and terminates all active sessions when the server exits. Use docker_interactive_list to view active sessions and docker_interactive_close to close them manually.

• docker_grep treats "no matches" as a successful result and still returns partial matches even if some paths cannot be read.

• docker_cp_to and docker_cp_from support recursive=true for directories. Local parent directories are created automatically when downloading. Remote parent directories must already exist before uploading (use docker_mkdir if needed).

• docker_close is a no-op because Docker does not keep a persistent connection per tool call.

Local Development

npm install
npm run check
npm test
npm start

Unit tests use createMockTransport() — the same Docker contract (exec / cp / close / spawnInteractive) executed in a local sandbox, without a real container.

To test the MCP protocol, use MCP Inspector or any MCP client that supports stdio transport.

CI / Release

GitHub Actions (.github/workflows/ci.yml):

1. Unit test (any branch/PR) — Node 18 / 22 / 24 → npm run check + npm run test:unit

2. MCP test (after unit) — same Node matrix × (node bin | npx from npm pack) with MCP_DOCKER_AGENTIC_MOCK=1

3. Push to master — after both pass, if tag vX.Y.Z is new: create tag → publish to GitHub Packages + npmjs

Local: npm run test:all

Bump version in package.json before merging to master for a new release. Re-merging the same version skips tag/publish.

Secrets: NPM_TOKEN. GitHub Packages uses GITHUB_TOKEN (packages: write).