devcontainer-mcp

A minimal Model Context Protocol server that exposes exactly one tool — bash — which mimics Claude Code's built-in Bash tool but executes every command inside a devcontainer instead of on the host.

The command runs via:

devcontainer exec --workspace-folder <folder> [--remote-env K=V ...] bash -lc "<command>"

and the tool returns the command's real combined stdout/stderr and exit code — not a static "Executed command …" string.

Addressed as mcp__devcontainer__bash (server name devcontainer, tool name bash).

Why

This is a Python rewrite of the TypeScript mcp-devcontainers server, trimmed to a single Bash-like tool and fixing its main defect: the original returned a fixed string and tee'd output to a file, so the model never saw what actually happened. Here, stdout/stderr and the exit status flow back in the tool result, and a non-zero exit (or a timeout) flags the result as an error.

It deliberately does not expose up, run-user-commands, or a generic exec — bringing the container up is out of scope for v1.

Related MCP server: Bash MCP Server

Requirements

• Python ≥ 3.10

• The @devcontainers/cli available as devcontainer on PATH (or override via DEVCONTAINER_CLI, e.g. npx @devcontainers/cli)

• A running devcontainer for the target workspace (start it yourself with devcontainer up --workspace-folder .)

Install / run

Run straight from the repo with uvx — no install step:

uvx --from git+https://github.com/vovayartsev-dice/devcontainer-mcp devcontainer-mcp

The server speaks MCP over stdio.

.mcp.json

Add it to your project's .mcp.json (the server key is what produces the mcp__devcontainer__* tool prefix):

{
  "mcpServers": {
    "devcontainer": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/vovayartsev-dice/devcontainer-mcp",
        "devcontainer-mcp"
      ],
      "env": {
        "DEVCONTAINER_WORKSPACE_FOLDER": "${workspaceFolder}"
      }
    }
  }
}

Configuration (environment variables)

The bash tool

Result

• Content is the combined stdout + stderr (interleaved), truncated to ~30 000 chars with a [output truncated] marker if longer.

• On a non-zero exit, the exit code is appended and isError is true.

• On a timeout, a timeout note is appended and isError is true.

Security / scope

• The command string is interpreted by bash only inside the container. The host process is launched argv-only (never shell=True, never a host sh -c), so host-side shell injection isn't possible.

• The container is the blast radius — this server does not mount the Docker socket, add --privileged, or expose any tool other than bash.

• v1 intentionally skips background execution / streaming and container bring-up.

Development

uv run devcontainer-mcp        # run the server from a checkout
uv build                       # build wheel + sdist