Client Configuration¶

KiCad MCP Pro works with MCP clients that can start a local stdio server or connect to a Streamable HTTP endpoint. The most portable setup is local stdio with uvx.

Replace /absolute/path/to/your/kicad-project with your KiCad project directory. You can omit KICAD_MCP_PROJECT_DIR and call kicad_set_project() from the client instead, but setting it once in the client config gives you a persistent default project.

Recommended Local Server¶

Use this command in clients that ask for a command and arguments:

command: uvx
args: ["kicad-mcp-pro"]

Recommended environment:

KICAD_MCP_PROJECT_DIR=/absolute/path/to/your/kicad-project
KICAD_MCP_PROFILE=pcb_only
KICAD_MCP_OPERATING_MODE=readonly

Use KICAD_MCP_PROFILE=full if you want every tool category. Preferred focused profiles are minimal, pcb_only, schematic_only, manufacturing, high_speed, power, simulation, and analysis. Legacy aliases pcb and schematic still work for older client configs. Profiles select a tool category set; KICAD_MCP_OPERATING_MODE is the risk gate applied on top. The default mode is readonly. Use write only for schematic or PCB source edits, manufacturing for release/export handoff tools, and experimental for routing, tuning, and unstable helpers.

CLI Setup Command Variants¶

Use these command variants when the client can register MCP servers from its CLI. Use the JSON or TOML config examples below for clients that only read config files.

Linux and macOS:

codex mcp add kicad \
  --env KICAD_MCP_PROJECT_DIR=/absolute/path/to/your/kicad-project \
  --env KICAD_MCP_PROFILE=pcb_only \
  --env KICAD_MCP_OPERATING_MODE=readonly \
  -- uvx kicad-mcp-pro

claude mcp add --transport stdio --scope project \
  --env KICAD_MCP_PROJECT_DIR=/absolute/path/to/your/kicad-project \
  --env KICAD_MCP_PROFILE=pcb_only \
  --env KICAD_MCP_OPERATING_MODE=readonly \
  kicad -- uvx kicad-mcp-pro

gemini mcp add --scope project --transport stdio \
  -e KICAD_MCP_PROJECT_DIR=/absolute/path/to/your/kicad-project \
  -e KICAD_MCP_PROFILE=pcb_only \
  -e KICAD_MCP_OPERATING_MODE=readonly \
  kicad uvx kicad-mcp-pro

Windows PowerShell:

codex mcp add kicad `
  --env 'KICAD_MCP_PROJECT_DIR=C:\absolute\path\to\your\kicad-project' `
  --env 'KICAD_MCP_PROFILE=pcb_only' `
  --env 'KICAD_MCP_OPERATING_MODE=readonly' `
  -- uvx kicad-mcp-pro

claude mcp add --transport stdio --scope project `
  --env 'KICAD_MCP_PROJECT_DIR=C:\absolute\path\to\your\kicad-project' `
  --env 'KICAD_MCP_PROFILE=pcb_only' `
  --env 'KICAD_MCP_OPERATING_MODE=readonly' `
  kicad -- uvx kicad-mcp-pro

gemini mcp add --scope project --transport stdio `
  -e 'KICAD_MCP_PROJECT_DIR=C:\absolute\path\to\your\kicad-project' `
  -e 'KICAD_MCP_PROFILE=pcb_only' `
  -e 'KICAD_MCP_OPERATING_MODE=readonly' `
  kicad uvx kicad-mcp-pro

VS Code And GitHub Copilot¶

VS Code uses .vscode/mcp.json for workspace-level configuration and a user profile MCP configuration for global setup. GitHub Copilot in VS Code uses the same MCP server setup. The repository ships .vscode/mcp.example.json as the copyable workspace example; place the same shape in .vscode/mcp.json for your own project.

.vscode/mcp.example.json:

{
  "servers": {
    "kicad": {
      "type": "stdio",
      "command": "uvx",
      "args": ["kicad-mcp-pro"],
      "env": {
        "KICAD_MCP_PROJECT_DIR": "/absolute/path/to/your/kicad-project",
        "KICAD_MCP_PROFILE": "pcb_only",
        "KICAD_MCP_OPERATING_MODE": "readonly"
      }
    }
  }
}

Use an absolute KiCad project path for KICAD_MCP_PROJECT_DIR. Some VS Code MCP setups do not expand ${workspaceFolder} and may fail at server startup.

Destination Paths¶

Copy the example into the client-owned config file. Keep repository examples inert by leaving their .example.* filenames unchanged. The Windows paths use %USERPROFILE% and %APPDATA% conventions used on Windows 11 and current supported Windows releases.

Client	Linux/macOS destination	Windows destination
VS Code and GitHub Copilot	`<project>/.vscode/mcp.json`, or the user-profile config opened by `MCP: Open User Configuration`	`<project>\.vscode\mcp.json`, or the user-profile config opened from VS Code
Codex CLI / IDE extension	`~/.codex/config.toml`, or a trusted `<project>/.codex/config.toml`	`%USERPROFILE%\.codex\config.toml`, or `<project>\.codex\config.toml`
Claude Code	`<project>/.mcp.json`, or use `claude mcp add --scope project`	`<project>\.mcp.json`, or use `claude mcp add --scope project`
Claude Desktop	macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`; Linux users should use Claude Code MCP	`%APPDATA%\Claude\claude_desktop_config.json`
Cursor	`<project>/.cursor/mcp.json` or `~/.cursor/mcp.json`	`<project>\.cursor\mcp.json` or `%USERPROFILE%\.cursor\mcp.json`
Gemini CLI	`~/.gemini/settings.json` or `<project>/.gemini/settings.json`	`%USERPROFILE%\.gemini\settings.json` or `<project>\.gemini\settings.json`
Generic stdio client	The client's MCP config file	The client's MCP config file
Generic HTTP client	The client's remote/HTTP MCP config file	The client's remote/HTTP MCP config file

Codex CLI And Codex IDE Extension¶

Codex stores MCP servers in ~/.codex/config.toml or a trusted project-scoped .codex/config.toml.

CLI setup:

codex mcp add kicad \
  --env KICAD_MCP_PROJECT_DIR=/absolute/path/to/your/kicad-project \
  --env KICAD_MCP_PROFILE=pcb_only \
  --env KICAD_MCP_OPERATING_MODE=readonly \
  -- uvx kicad-mcp-pro

~/.codex/config.toml:

[mcp_servers.kicad]
command = "uvx"
args = ["kicad-mcp-pro"]
startup_timeout_sec = 20
tool_timeout_sec = 120

[mcp_servers.kicad.env]
KICAD_MCP_PROJECT_DIR = "/absolute/path/to/your/kicad-project"
KICAD_MCP_PROFILE = "pcb_only"
KICAD_MCP_OPERATING_MODE = "readonly"

Claude Desktop¶

Add the server to claude_desktop_config.json:

{
  "mcpServers": {
    "kicad": {
      "command": "uvx",
      "args": ["kicad-mcp-pro"],
      "env": {
        "KICAD_MCP_PROJECT_DIR": "/absolute/path/to/your/kicad-project",
        "KICAD_MCP_PROFILE": "pcb_only",
        "KICAD_MCP_OPERATING_MODE": "readonly"
      }
    }
  }
}

Claude Code¶

Use KiCad MCP Pro 1.0.0 or newer for Claude Code stdio setups. That release defers heavy tool registration until after the MCP initialize handshake, avoiding startup races on slower WSL or cold KiCad environments.

Project-scoped .mcp.json:

{
  "mcpServers": {
    "kicad": {
      "command": "uvx",
      "args": ["kicad-mcp-pro"],
      "env": {
        "KICAD_MCP_PROJECT_DIR": "/absolute/path/to/your/kicad-project",
        "KICAD_MCP_PROFILE": "pcb_only",
        "KICAD_MCP_OPERATING_MODE": "readonly"
      }
    }
  }
}

CLI setup:

claude mcp add kicad \
  --scope project \
  --env KICAD_MCP_PROJECT_DIR=/absolute/path/to/your/kicad-project \
  --env KICAD_MCP_PROFILE=pcb_only \
  --env KICAD_MCP_OPERATING_MODE=readonly \
  -- uvx kicad-mcp-pro

Cursor¶

Use .cursor/mcp.json for project configuration or ~/.cursor/mcp.json for global configuration:

{
  "mcpServers": {
    "kicad": {
      "type": "stdio",
      "command": "uvx",
      "args": ["kicad-mcp-pro"],
      "env": {
        "KICAD_MCP_PROJECT_DIR": "/absolute/path/to/your/kicad-project",
        "KICAD_MCP_PROFILE": "pcb_only",
        "KICAD_MCP_OPERATING_MODE": "readonly"
      }
    }
  }
}

Gemini CLI¶

Add the server to ~/.gemini/settings.json:

{
  "mcpServers": {
    "kicad": {
      "command": "uvx",
      "args": ["kicad-mcp-pro"],
      "env": {
        "KICAD_MCP_PROJECT_DIR": "/absolute/path/to/your/kicad-project",
        "KICAD_MCP_PROFILE": "pcb_only",
        "KICAD_MCP_OPERATING_MODE": "readonly"
      },
      "timeout": 120000
    }
  }
}

Antigravity And Other MCP Clients¶

If your client accepts the common mcpServers JSON shape, use this as the starting point:

{
  "mcpServers": {
    "kicad": {
      "type": "stdio",
      "command": "uvx",
      "args": ["kicad-mcp-pro"],
      "env": {
        "KICAD_MCP_PROJECT_DIR": "/absolute/path/to/your/kicad-project",
        "KICAD_MCP_PROFILE": "pcb_only",
        "KICAD_MCP_OPERATING_MODE": "readonly"
      }
    }
  }
}

Client-specific behavior can vary. If the client supports only HTTP servers, use the HTTP setup below.

Streamable HTTP Setup¶

Start KiCad MCP Pro as an HTTP server:

Linux and macOS:

KICAD_MCP_PROJECT_DIR=/absolute/path/to/your/kicad-project \
KICAD_MCP_PROFILE=pcb_only \
KICAD_MCP_OPERATING_MODE=readonly \
uvx kicad-mcp-pro --transport http --host 127.0.0.1 --port 3334

Windows PowerShell:

$Env:KICAD_MCP_PROJECT_DIR = 'C:\absolute\path\to\your\kicad-project'
$Env:KICAD_MCP_PROFILE = 'pcb_only'
$Env:KICAD_MCP_OPERATING_MODE = 'readonly'
uvx kicad-mcp-pro --transport http --host 127.0.0.1 --port 3334

The default endpoint is:

http://127.0.0.1:3334/mcp

The loopback examples above do not need KICAD_MCP_AUTH_TOKEN. Set KICAD_MCP_AUTH_TOKEN only when HTTP binds outside loopback or crosses a tunnel or remote network boundary. Clients must then send the same value as a bearer token. Store the token in local environment or secret storage and never in a checked-in config example.

VS Code HTTP example:

{
  "servers": {
    "kicad": {
      "type": "http",
      "url": "http://127.0.0.1:3334/mcp"
    }
  }
}

Codex HTTP example:

[mcp_servers.kicad]
url = "http://127.0.0.1:3334/mcp"
tool_timeout_sec = 120

Gemini CLI HTTP example:

{
  "mcpServers": {
    "kicad": {
      "httpUrl": "http://127.0.0.1:3334/mcp",
      "timeout": 120000
    }
  }
}

References¶

Agent onboarding and examples: ../../../docs/agents/client-configs.md
VS Code MCP configuration: https://code.vscode.dev/docs/copilot/customization/mcp-servers
Codex MCP configuration: https://developers.openai.com/codex/config-reference
Claude Code MCP configuration: https://docs.anthropic.com/en/docs/claude-code/mcp
Anthropic MCP overview: https://docs.anthropic.com/en/docs/mcp
Cursor MCP configuration: https://docs.cursor.com/en/context/mcp
Gemini CLI MCP setup notes: https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md