Docker Install

The runtime image is published to GitHub Container Registry:

ghcr.io/oaslananka/kicad-mcp-pro

The image runs as the non-root kicadmcp user, exposes port 3334, and starts kicad-mcp-pro --transport streamable-http by default. It binds to 0.0.0.0 inside the container so Docker port publishing reaches the server; keep the published host port on loopback unless a trusted proxy or tunnel handles access. It does not contain secrets.

Help Smoke Test

docker run --rm ghcr.io/oaslananka/kicad-mcp-pro:latest --help

For reproducible deployments, pin the image by a version tag or immutable GHCR digest:

docker run --rm ghcr.io/oaslananka/kicad-mcp-pro:<version> --help
docker run --rm ghcr.io/oaslananka/kicad-mcp-pro@sha256:<digest> --help

Streamable HTTP

Run the default streamable HTTP server for local connector testing:

docker run --rm \
  -p 127.0.0.1:3334:3334 \
  -e KICAD_MCP_AUTH_TOKEN="replace-with-strong-32-character-token" \
  -e KICAD_MCP_PROJECT_DIR=/projects \
  -v "$PWD:/projects:ro" \
  ghcr.io/oaslananka/kicad-mcp-pro:<version>

The MCP endpoint is http://127.0.0.1:3334/mcp. Binding HTTP to 0.0.0.0 requires KICAD_MCP_AUTH_TOKEN; keep the published Docker port bound to loopback unless a reverse proxy or tunnel terminates authentication.

stdio Override

Use this form for MCP clients that communicate over standard input and output:

docker run --rm -i \
  -e KICAD_MCP_PROJECT_DIR=/projects \
  -v "$PWD:/projects:ro" \
  ghcr.io/oaslananka/kicad-mcp-pro:<version> \
  --transport stdio

Claude Desktop stdio example:

{
  "mcpServers": {
    "kicad-mcp-pro": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "/absolute/path/to/project:/projects:ro",
        "-e",
        "KICAD_MCP_PROJECT_DIR=/projects",
        "ghcr.io/oaslananka/kicad-mcp-pro:<version>",
        "--transport",
        "stdio"
      ]
    }
  }
}

KiCad CLI

The published runtime image keeps KiCad external so operators can choose the KiCad version that matches their projects. File-backed DRC, ERC, export, and quality-gate tools need kicad-cli available inside the container through one of these paths:

• mount a host-managed KiCad install and set KICAD_MCP_KICAD_CLI;
• build locally with --build-arg KICAD_CLI_APK_PACKAGE=kicad when the Alpine distribution package is acceptable for the target platform;
• build with --build-arg KICAD_VERSION=kicad10 for CI images that extract an official KiCad 10 AppImage at build time (see Dockerfile multi-stage).

Redistributing images that bundle KiCad CLI brings KiCad's upstream license terms into the image supply chain. Review the official KiCad licenses before publishing a derived image with KiCad included.

Compose

A Docker Compose example lives in the repository at examples/mcp-docker. It mounts a KiCad project read-only, exposes the HTTP endpoint on localhost, and keeps output files in a named volume.