Skip to content

Docker Deployment

For install and client examples, see Docker Install.

The published image is ghcr.io/oaslananka/kicad-mcp-pro. It is built from the multi-stage packages/mcp-server/Dockerfile, runs as a non-root user, exposes port 3334, and defaults to streamable HTTP. It binds to 0.0.0.0 inside the container so Docker port publishing can reach the server.

Local HTTP Service

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 \
  -e KICAD_MCP_OUTPUT_DIR=/tmp/kicad-mcp-output \
  -v "$PWD:/projects:ro" \
  -v kicad-mcp-output:/tmp/kicad-mcp-output \
  ghcr.io/oaslananka/kicad-mcp-pro:<version>

Use http://127.0.0.1:3334/mcp as the MCP URL. Do not expose this container on a public interface without a bearer token, strict CORS origins, and a TLS terminating proxy or tunnel.

Volume Mounts

  • Mount KiCad projects read-only at /projects for analysis, DRC, ERC, and export workflows.
  • Set KICAD_MCP_PROJECT_DIR=/projects so tools resolve relative project paths inside the container.
  • Mount a writable output location such as /tmp/kicad-mcp-output for generated manufacturing files.
  • If KiCad is installed outside the image, mount the directory containing kicad-cli and set KICAD_MCP_KICAD_CLI to its in-container path.

Environment Variables

Variable Purpose
KICAD_MCP_TRANSPORT Defaults to streamable-http; set stdio only when overriding the Docker command for stdio clients.
KICAD_MCP_HOST Defaults to 0.0.0.0 inside Docker so published port 3334 reaches the server.
KICAD_MCP_PORT Defaults to 3334.
KICAD_MCP_AUTH_TOKEN Required when HTTP binds outside loopback. Use a 32+ character token and pass it as a bearer token from clients.
KICAD_MCP_PROJECT_DIR In-container project mount path, typically /projects.
KICAD_MCP_OUTPUT_DIR Writable output directory for generated artifacts.
KICAD_MCP_KICAD_CLI Optional path to kicad-cli if it is mounted or bundled.

Docker Compose

The repository example at examples/mcp-docker starts the HTTP service with a read-only project mount:

export KICAD_MCP_AUTH_TOKEN="replace-with-strong-32-character-token"
docker compose -f examples/mcp-docker/docker-compose.yml up

Override KICAD_PROJECT_DIR to point at a local KiCad project.

ChatGPT Connector Recipe

  1. Start the container or Compose service on localhost with KICAD_MCP_AUTH_TOKEN set.
  2. Expose the local endpoint through an HTTPS tunnel such as Cloudflare Tunnel:

bash cloudflared tunnel --url http://127.0.0.1:3334

  1. In the ChatGPT connector configuration, set the MCP URL to https://<tunnel-host>/mcp.
  2. Configure authentication as a bearer token using the same KICAD_MCP_AUTH_TOKEN.
  3. Keep the KiCad project mounted read-only unless the workflow intentionally writes generated project files.

KiCad CLI Images

The default published image keeps KiCad external. To install the Alpine distribution package during a local build, pass its APK package name:

docker build \
  --build-arg KICAD_CLI_APK_PACKAGE=kicad \
  -t kicad-mcp-pro:kicad-cli .

For CI jobs that need a self-contained KiCad 10 CLI, build with the kicad10 variant. Pass an official Linux x86_64 KiCad 10 AppImage URL from the KiCad Linux download page:

docker build \
  --build-arg KICAD_VERSION=kicad10 \
  --build-arg KICAD_APPIMAGE_URL="https://downloads.kicad.org/path/to/KiCad-10.x-x86_64.AppImage" \
  -t ghcr.io/oaslananka/kicad-mcp-pro:kicad10-ci .

The bundled KiCad 10 image binds its HTTP server to 127.0.0.1 by default so it remains usable for CI smoke checks without requiring a baked-in token.

Redistributing an image with KiCad CLI included adds KiCad's upstream license terms to the derived image. Review the official KiCad licenses before publishing such an image.