zeughaus-mcp

MCP Server - Agentic Workbench backed by Nixery.

Execute commands in ephemeral containers with any combination of Nix packages.

Installation

Docker (recommended)

Docker is the recommended installation method because it provides workspace isolation - the MCP server itself runs in a container with access only to your specified workspace directory.

docker run --rm -i \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /path/to/workspace:/workspace \
  -e NIXERY_REGISTRY_URL=nixery.zeughaus.dev \
  -e HOST_WORKSPACE_ROOT=/path/to/workspace \
  ghcr.io/gtarkin/zeughaus_mcp:latest

uvx (alternative)

Note: When running via uvx, the MCP server has full access to the host system. Use Docker for better isolation.

uvx zeughaus-mcp

Configuration

Environment variables:

Variable	Required	Default	Description
NIXERY_REGISTRY_URL	Yes	-	Nixery registry URL (see below)
HOST_WORKSPACE_ROOT	Yes	-	Workspace path to mount into containers
DOCKER_NETWORK_MODE	No	host	Docker network mode
CONTAINER_TIMEOUT_SECONDS	No	300	Container execution timeout

Nixery Registries

Nixery is a Docker-compatible registry that builds container images on-the-fly from Nix packages.

Available Registries

Registry	Channel	Description
nixery.zeughaus.dev	nixos-25.11	Self-hosted instance for zeughaus-mcp (recommended)
nixery.dev	nixos-unstable	Public Nixery instance by Google

nixery.zeughaus.dev (Recommended)

The default registry for zeughaus-mcp. This is a self-hosted Nixery instance with:

• Nix Channel: nixos-25.11 (stable packages)
• Source: github.com/NixOS/nixpkgs
• Build timeout: 600 seconds

nixery.dev (Alternative)

The public Nixery instance maintained by Google. Use this if you prefer:

• Nix Channel: nixos-unstable (latest packages)
• No dependency on third-party infrastructure

To use the public registry, set:

NIXERY_REGISTRY_URL=nixery.dev

MCP Client Configuration

Claude Desktop (Docker - recommended)

{
  "mcpServers": {
    "zeughaus": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/var/run/docker.sock:/var/run/docker.sock",
        "-v", "/path/to/workspace:/workspace",
        "-e", "NIXERY_REGISTRY_URL=nixery.zeughaus.dev",
        "-e", "HOST_WORKSPACE_ROOT=/path/to/workspace",
        "ghcr.io/gtarkin/zeughaus_mcp:latest"
      ]
    }
  }
}

Claude Desktop (uvx)

{
  "mcpServers": {
    "zeughaus": {
      "command": "uvx",
      "args": ["zeughaus-mcp"],
      "env": {
        "NIXERY_REGISTRY_URL": "nixery.zeughaus.dev",
        "HOST_WORKSPACE_ROOT": "/path/to/workspace"
      }
    }
  }
}

License

MIT