# tejasvaradaraj/kicad_mcp_server architecture

> Architecture diagram of the GitHub repository tejasvaradaraj/kicad_mcp_server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tejasvaradaraj/kicad_mcp_server
- Repository: https://github.com/tejasvaradaraj/kicad_mcp_server

## Overview

KiCad MCP exposes tools to an LLM for inspecting and lightly editing the PCB currently open in KiCad, then exporting manufacturing and documentation files. The main workflow is client → MCP tool registration/dispatch → KiCad connection → board or project operation; exports snapshot the open board and invoke kicad-cli. Separate capabilities cover connection/document discovery, board data and edits, geometry/common helpers, and project metadata. An optional HTTP path adds Google authorization and a Cloudflare tunnel. Unshown tool internals are represented only where README capabilities support them.

Main entry points: [`kicad_mcp/server.py`](https://github.com/tejasvaradaraj/kicad_mcp_server/blob/main/kicad_mcp/server.py) (Tool Registry), [`kicad_mcp/connection.py`](https://github.com/tejasvaradaraj/kicad_mcp_server/blob/main/kicad_mcp/connection.py) (IPC Connection), [`kicad_mcp/tools/board.py`](https://github.com/tejasvaradaraj/kicad_mcp_server/blob/main/kicad_mcp/tools/board.py) (Board Inspection & Edits), [`remote/http_server.py`](https://github.com/tejasvaradaraj/kicad_mcp_server/blob/main/remote/http_server.py) (HTTP MCP Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["MCP Interface"]
  node_stdio["stdio Entry<br/>[server.py]"]
  node_mcp["Tool Registry<br/>[server.py]"]
end

subgraph group_integration["KiCad Integration"]
  node_core["Connection &amp; Documents<br/>[kicad_core.py]"]
  node_connection["IPC Connection<br/>[connection.py]"]
  node_dochelpers["Document Helpers<br/>[documents.py]"]
end

subgraph group_board["Board Tools"]
  node_board["Board Inspection &amp; Edits<br/>[board.py]"]
  node_boardtypes["Board Types<br/>[board_types.py]"]
  node_geometry["Geometry Tools<br/>[geometry_utils.py]"]
  node_common["Units &amp; Layers<br/>[common_types.py]"]
  node_layerhelpers["Layer Helpers<br/>[layers.py]"]
  node_cli["Export Helper<br/>[cli.py]"]
end

subgraph group_project["Project Tools"]
  node_project["Project Metadata<br/>[project.py]"]
end

subgraph group_remote["Remote Access"]
  node_http["HTTP MCP Server<br/>[http_server.py]"]
  node_oauth["Google OAuth Provider<br/>[google_oauth.py]"]
end

node_llm(("LLM Client"))
node_kicad["KiCad GUI"]
node_kicadcli["kicad-cli"]
node_google["Google Login"]
node_cloudflare["Cloudflare Tunnel"]

node_llm -->|"starts locally"| node_stdio
node_stdio -->|"runs"| node_mcp
node_llm -.->|"calls remotely"| node_http
node_http -.->|"creates"| node_mcp
node_mcp -->|"registers tools"| node_core
node_mcp -->|"registers tools"| node_board
node_mcp -->|"registers tools"| node_boardtypes
node_mcp -->|"registers tools"| node_geometry
node_mcp -->|"registers tools"| node_common
node_mcp -->|"registers tools"| node_project
node_core -->|"gets client"| node_connection
node_core -->|"formats documents"| node_dochelpers
node_board -->|"gets board"| node_connection
node_board -->|"uses layer IDs"| node_layerhelpers
node_boardtypes -->|"uses KiCad"| node_connection
node_geometry -->|"uses KiCad"| node_connection
node_common -->|"uses KiCad"| node_connection
node_project -->|"gets project"| node_connection
node_project -->|"uses document types"| node_dochelpers
node_connection -->|"connects via IPC"| node_kicad
node_board -->|"requests exports"| node_cli
node_cli -->|"reads board snapshot"| node_connection
node_cli -->|"runs exports"| node_kicadcli
node_http -.->|"handles callback"| node_oauth
node_oauth -.->|"exchanges login"| node_google
node_http -.->|"starts tunnel"| node_cloudflare

click node_stdio "https://github.com/tejasvaradaraj/kicad_mcp_server/blob/main/server.py"
click node_mcp "https://github.com/tejasvaradaraj/kicad_mcp_server/blob/main/kicad_mcp/server.py"
click node_core "https://github.com/tejasvaradaraj/kicad_mcp_server/blob/main/kicad_mcp/tools/kicad_core.py"
click node_connection "https://github.com/tejasvaradaraj/kicad_mcp_server/blob/main/kicad_mcp/connection.py"
click node_board "https://github.com/tejasvaradaraj/kicad_mcp_server/blob/main/kicad_mcp/tools/board.py"
click node_boardtypes "https://github.com/tejasvaradaraj/kicad_mcp_server/blob/main/kicad_mcp/tools/board_types.py"
click node_geometry "https://github.com/tejasvaradaraj/kicad_mcp_server/blob/main/kicad_mcp/tools/geometry_utils.py"
click node_common "https://github.com/tejasvaradaraj/kicad_mcp_server/blob/main/kicad_mcp/tools/common_types.py"
click node_layerhelpers "https://github.com/tejasvaradaraj/kicad_mcp_server/blob/main/kicad_mcp/helpers/layers.py"
click node_project "https://github.com/tejasvaradaraj/kicad_mcp_server/blob/main/kicad_mcp/tools/project.py"
click node_dochelpers "https://github.com/tejasvaradaraj/kicad_mcp_server/blob/main/kicad_mcp/helpers/documents.py"
click node_cli "https://github.com/tejasvaradaraj/kicad_mcp_server/blob/main/kicad_mcp/helpers/cli.py"
click node_http "https://github.com/tejasvaradaraj/kicad_mcp_server/blob/main/remote/http_server.py"
click node_oauth "https://github.com/tejasvaradaraj/kicad_mcp_server/blob/main/remote/google_oauth.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_stdio,node_mcp,node_llm,node_kicad toneBlue
class node_core,node_connection,node_dochelpers toneAmber
class node_board,node_boardtypes,node_geometry,node_common,node_layerhelpers,node_cli toneMint
class node_project toneRose
class node_http,node_oauth,node_kicadcli,node_google,node_cloudflare toneIndigo
```

## Components

### MCP Interface

- [stdio Entry](https://github.com/tejasvaradaraj/kicad_mcp_server/blob/main/server.py): `server.py`
- [Tool Registry](https://github.com/tejasvaradaraj/kicad_mcp_server/blob/main/kicad_mcp/server.py): `kicad_mcp/server.py`

### KiCad Integration

- [Connection & Documents](https://github.com/tejasvaradaraj/kicad_mcp_server/blob/main/kicad_mcp/tools/kicad_core.py): `kicad_mcp/tools/kicad_core.py`
- [IPC Connection](https://github.com/tejasvaradaraj/kicad_mcp_server/blob/main/kicad_mcp/connection.py): `kicad_mcp/connection.py`
- [Document Helpers](https://github.com/tejasvaradaraj/kicad_mcp_server/blob/main/kicad_mcp/helpers/documents.py): `kicad_mcp/helpers/documents.py`

### Board Tools

- [Board Inspection & Edits](https://github.com/tejasvaradaraj/kicad_mcp_server/blob/main/kicad_mcp/tools/board.py): `kicad_mcp/tools/board.py`
- [Board Types](https://github.com/tejasvaradaraj/kicad_mcp_server/blob/main/kicad_mcp/tools/board_types.py): `kicad_mcp/tools/board_types.py`
- [Geometry Tools](https://github.com/tejasvaradaraj/kicad_mcp_server/blob/main/kicad_mcp/tools/geometry_utils.py): `kicad_mcp/tools/geometry_utils.py`
- [Units & Layers](https://github.com/tejasvaradaraj/kicad_mcp_server/blob/main/kicad_mcp/tools/common_types.py): `kicad_mcp/tools/common_types.py`
- [Layer Helpers](https://github.com/tejasvaradaraj/kicad_mcp_server/blob/main/kicad_mcp/helpers/layers.py): `kicad_mcp/helpers/layers.py`
- [Export Helper](https://github.com/tejasvaradaraj/kicad_mcp_server/blob/main/kicad_mcp/helpers/cli.py): `kicad_mcp/helpers/cli.py`

### Project Tools

- [Project Metadata](https://github.com/tejasvaradaraj/kicad_mcp_server/blob/main/kicad_mcp/tools/project.py): `kicad_mcp/tools/project.py`

### Remote Access

- [HTTP MCP Server](https://github.com/tejasvaradaraj/kicad_mcp_server/blob/main/remote/http_server.py): `remote/http_server.py`
- [Google OAuth Provider](https://github.com/tejasvaradaraj/kicad_mcp_server/blob/main/remote/google_oauth.py): `remote/google_oauth.py`

### Other components

- **LLM Client**
- **KiCad GUI**
- **kicad-cli**
- **Google Login**
- **Cloudflare Tunnel**

## Connections

- LLM Client → stdio Entry: starts locally
- stdio Entry → Tool Registry: runs
- LLM Client → HTTP MCP Server: calls remotely
- HTTP MCP Server → Tool Registry: creates
- Tool Registry → Connection & Documents: registers tools
- Tool Registry → Board Inspection & Edits: registers tools
- Tool Registry → Board Types: registers tools
- Tool Registry → Geometry Tools: registers tools
- Tool Registry → Units & Layers: registers tools
- Tool Registry → Project Metadata: registers tools
- Connection & Documents → IPC Connection: gets client
- Connection & Documents → Document Helpers: formats documents
- Board Inspection & Edits → IPC Connection: gets board
- Board Inspection & Edits → Layer Helpers: uses layer IDs
- Board Types → IPC Connection: uses KiCad
- Geometry Tools → IPC Connection: uses KiCad
- Units & Layers → IPC Connection: uses KiCad
- Project Metadata → IPC Connection: gets project
- Project Metadata → Document Helpers: uses document types
- IPC Connection → KiCad GUI: connects via IPC
- Board Inspection & Edits → Export Helper: requests exports
- Export Helper → IPC Connection: reads board snapshot
- Export Helper → kicad-cli: runs exports
- HTTP MCP Server → Google OAuth Provider: handles callback
- Google OAuth Provider → Google Login: exchanges login
- HTTP MCP Server → Cloudflare Tunnel: starts tunnel