container-mcp
Allows managing Apple containers (VM-isolated sandboxes) on macOS, providing tools for running, executing, listing, and managing container lifecycle, images, and system status.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@container-mcp run a container with Ubuntu and execute 'uname -a'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
container-mcp
Run AI agents in real VM sandboxes on your Mac — fully local, safe by default.
An MCP server for Apple containers — every container gets its own VM, which makes it the right isolation boundary for code an AI agent wrote five seconds ago. No daemon, no account, no cloud.
Part of a larger toolkit: a native macOS "mission control" GUI for agent sandboxes is in development.
Requirements — read before installing. This server shells out to Apple's
container CLI, which only runs on Apple silicon Macs (M-series) on macOS 26
or newer. There is no Linux, Intel, or pre-26 fallback — the server will
install but every tool call fails without a working container CLI.
Apple silicon Mac (arm64)
macOS 26 (Tahoe) or newer
Node.js 20+
Verify the CLI is present before going further: container --version
Why
Real VM isolation, per container — each sandbox gets its own kernel via Apple's container runtime: the right boundary for agent-written code, not a shared-kernel namespace
Local-first and private — no daemon, no account, no cloud; network is denied by default, so nothing leaves your Mac unless you allow it
Safe by default, and visible — explicit mount allowlist, default-deny network, and managed-label scoping; the boundary is meant to be seen, not buried in config
Self-healing errors — every failure tells the agent how to fix it
Agent-aware — every container is labeled with the session and client that created it
Related MCP server: Sandbox Compute Broker
Install
Meets the requirements above? Install with one command (no clone, no build):
claude mcp add container -- npx -y container-mcpOr point any MCP client's config at the published binary:
{
"mcpServers": {
"container": { "command": "npx", "args": ["-y", "container-mcp"] }
}
}git clone https://github.com/mustafaTokmak/container-mcp.git
cd container-mcp
npm install && npm run build
claude mcp add container -- node "$(pwd)/dist/index.js"Verify it works
After adding the server, confirm the toolchain end-to-end by asking your agent to check (and start) the container system service:
Use the system_status tool with start: true.A healthy setup returns running (or container system service started on first
start). An error here means the container CLI isn't installed or you're not on
macOS 26+ — fix that before trying other tools.
Try it — the aha moment
Ask your agent to run untrusted code in a throwaway VM and hand back the output — no daemon, no cloud, network denied by default:
Run python:3.12-alpine in a container with wait: true and
command ["python", "-c", "print(sum(range(1000)))"]. Show me the output.The agent calls run_container with wait: true, the code executes inside its
own VM with no network access, and you get back a structured result:
499500That container had its own kernel, couldn't reach the network, and is gone when
you remove it (remove_container) — the right blast radius for code an agent
wrote five seconds ago. Want it to reach the network? Add network: true to the
same request.
Tools
Tool | Description |
| Run an image in its own VM (labeled, resource-limited; |
| Run a command in a running container (returns structured |
| Inspect state and output |
| Snapshot CPU, memory, and I/O usage for a running container as JSON |
| Full container detail (configuration, mounts, labels, network, status) as JSON |
| Lifecycle |
| Copy between host and container |
| Image management |
| Remove images to reclaim disk |
| Check/start the container system service |
Safety model
Env var | Default | Effect |
| launch dir + private scratch dir | Colon-separated allowlist of host paths agents may mount, copy to/from, or build from. Setting it replaces the default. |
| off |
|
| off |
|
|
| CPU limit applied when the agent does not specify one |
|
| Memory limit applied when the agent does not specify one |
|
| Value of the |
|
| Base CLI timeout in ms. Image pulls/builds and wait-mode runs get 600000 automatically. |
|
| Maximum concurrent containers run_container will create |
| off |
|
Mount sources, build contexts, and dockerfiles must exist and are fully
canonicalized (symlinks resolved) before allowlist checks — a path cannot be
swapped for a symlink after validation. A launch directory of / or your home
directory is never used as an implicit allowlist root. Lifecycle tools
(stop, remove, exec, logs, copy) only operate on containers this server
created (tagged dev.container-mcp.managed=true) unless
CONTAINER_MCP_ALLOW_UNMANAGED is set. Every agent-supplied value that
reaches the CLI is guarded against flag injection, and commands are executed
with execFile (no shell), so there is no shell injection surface.
Containers have no outbound network by default (run with --network none); set
CONTAINER_MCP_ALLOW_NETWORK or pass network: true per run to enable egress.
Every container is labeled with a per-session id and the connecting MCP client's
name (dev.container-mcp.session, dev.container-mcp.client) so a session view
can attribute containers truthfully across concurrent agents.
Verified against the real CLI
These were doc-only assumptions; the live suite now runs against container 1.0.0 on macOS 26 and confirms (or corrected) each:
container exectakes no--terminator — Apple captures everything after the container id as the process argv verbatim (passing--makes--the target executable and fails). Corrected 2026-06-14; a leading-dash command token is treated as a literal executable and fails closed, so dropping--opens no flag-injection path.container cpround-trips a file host → container → host. ✅ confirmed.container inspectnests labels underconfiguration.labels; managed-label checks parse it tolerantly and fail closed (override:CONTAINER_MCP_ALLOW_UNMANAGED). ✅ confirmed.container run --network nonedisables egress (thenonevalue is accepted). ✅ confirmed.
Each has a dedicated test in the live suite below.
Development
npm install
npm test # unit + integration suite; no container CLI required
npm run buildCONTAINER_MCP_LIVE=1 npm test additionally runs the live end-to-end suite
(test/live.test.ts), which requires the container CLI,
pulls alpine:latest, and creates real containers. It is the pre-release
gate that verifies the known assumptions above against real hardware. CI
runs the regular suite on macOS for every push.
License
MIT
Available Tools
15 toolsbuild_imageBuild imageB
Build an image from a Dockerfile. The build context must be inside an allowed host path.
Inputs: tag (required), context (required), dockerfile.
container_logsContainer logsARead-only
Fetch the most recent log lines from a container (default: last 100). The tail is applied server-side via the CLI -n flag.
Inputs: id (required), tail.
container_statsContainer statsARead-only
Snapshot CPU, memory, and I/O usage for a container as JSON.
Inputs: id (required).
copy_filesCopy filesADestructive
Copy files between host and container. Container paths use ':'. Host paths must be inside the allowed roots.
Inputs: source (required), destination (required).
exec_in_containerExecute in containerB
Run a command inside a running container and return its output.
Inputs: id (required), command (required).
inspect_containerInspect containerARead-only
Full container details (configuration, mounts, labels, network, status) as JSON.
Inputs: id (required).
list_containersList containersARead-only
List containers as JSON. Pass all: true to include stopped containers.
Inputs: all.
list_imagesList imagesARead-only
List local container images as JSON.
Inputs: no named parameters.
prune_imagesPrune imagesADestructive
Remove dangling images to reclaim disk. Pass all: true to remove all unused images.
Inputs: all.
pull_imagePull imageB
Pull an OCI image from a registry, e.g. 'alpine:latest'.
Inputs: reference (required).
remove_containerRemove containerADestructive
Delete a container. Pass force: true to delete a running container.
Inputs: id (required), force.
remove_imageRemove imageADestructive
Delete a local image by reference. Pass force: true to remove even if in use.
Inputs: reference (required), force.
run_containerRun containerA
Run a container inside its own lightweight VM. By default runs detached and returns the container ID. Pass wait: true to run to completion and return the container's output (10 minute limit). Mount sources must be inside the allowed host paths. Default CPU/memory limits are applied unless overridden.
Inputs: image (required), env, cpus, name, +7 more.
stop_containerStop containerC
Stop a running container.
Inputs: id (required).
system_statusContainer system statusA
Check whether the Apple container system service is running. Pass start: true to start it if it is stopped.
Inputs: start.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Each tool targets a distinct operation—containers vs images, lifecycle vs inspection vs logs—with no overlapping functionality. An agent can easily select the correct tool.
All tool names follow a consistent verb_noun pattern using snake_case, e.g., list_containers, run_container, pull_image. Minor variations like container_logs are still clear and predictable.
With 15 tools, the set is well-scoped for container management—covering containers, images, and system status without being overwhelming or sparse.
Covers essential container and image lifecycle operations (CRUD, logs, stats, exec, copy, pull, build, prune). Missing operations like commit or rename are tertiary; the surface is highly functional.
Maintenance
Related MCP Connectors
Linux microVM sandboxes for AI agents: run commands, files, processes, pause and wake.
Sealed microVM sandboxes for AI agents: run untrusted code locally or in kosa8 Cloud.
Cloud Linux VMs for your agent: run code, Docker, files and HTTPS previews in a Sandboxer microVM.
Secure Linux sandboxes for AI agents, as MCP tools.
Related MCP Servers
- AlicenseAqualityDmaintenanceProvides a local, isolated Linux VM sandbox for AI agents using Apple's Virtualization.framework, enabling fast command execution (~60ms) and package management without cloud costs.351MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to run compute tasks in secure sandboxes with optional interactive UIs, brokering between agents and isolated execution environments.Apache 2.0
- FlicenseNot gradedqualityAmaintenanceLets AI agents manage local virtual machines: create macOS and Linux VMs on Apple silicon and WSL distros on Windows, start/stop, clone, back up, and run commands inside them.4,068-

Runtimeofficial
AlicenseNot gradedqualityBmaintenanceLinux sandboxes for AI agents, each a Firecracker microVM. Run code, keep files, pause and wake with memory kept, snapshot and fork.2Apache 2.0