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.

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)

Variable	Default	Purpose
DEVCONTAINER_CLI	devcontainer	CLI invocation; shell-split, so npx @devcontainers/cli works.
DEVCONTAINER_WORKSPACE_FOLDER	current dir	Default host workspace folder when the workspaceFolder arg is omitted.

The bash tool

Field	Type	Required	Default	Notes
command	string	✅	—	Run via bash -lc "<command>" inside the container. Pipes/&&/globs/redirects work.
cwd	string		workspace root	Working dir inside the container: cd <cwd> && ( <command> ).
env	object {KEY: VAL} or list KEY=VAL		—	Forwarded as repeated --remote-env.
timeout	integer (ms)		120000 (max 600000)	On timeout the process group is killed; result flagged as error.
description	string		—	Logged for observability; otherwise unused.
workspaceFolder	string		cwd / env var	Host path holding the .devcontainer config.

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