KiCAD-MCP-Server

KiCAD MCP é uma implementação do Model Context Protocol (MCP) que permite que Modelos de Linguagem de Grande Escala (LLMs) como o Claude interajam diretamente com o KiCAD para design de placas de circuito impresso.

GitHub

1.9k

Documentação

Discussões. Entre aqui.

https://github.com/mixelpixx/KiCAD-MCP-Server/discussions/73

🚀 Conheça o Konnect — a próxima geração

Konnect é este projeto reconstruído do zero em Rust como um plugin nativo do KiCAD 10: um único binário sem dependências de runtime, construído sobre a API IPC oficial do KiCAD em vez do SWIG, com 171 ferramentas, skills e agentes Claude integrados, auditorias de revisão de design e um pipeline de fabricação. É onde o novo desenvolvimento acontece — licenciado AGPL-3.0 (gratuito para indivíduos e código aberto; licenças comerciais disponíveis para empresas).

Este servidor Python/TypeScript permanece totalmente aberto (MIT) e mantido.

Servidor MCP KiCAD

Um servidor Model Context Protocol (MCP) que permite que assistentes de IA como o Claude interajam com o KiCAD para automação de design de PCB. Construído sobre a especificação MCP 2025-06-18, este servidor fornece esquemas de ferramentas abrangentes e acesso ao estado do projeto em tempo real para fluxos de trabalho inteligentes de design de PCB.

Visão geral

O Model Context Protocol é um padrão aberto da Anthropic que permite que assistentes de IA se conectem com segurança a ferramentas e fontes de dados externas. Esta implementação fornece uma ponte padronizada entre assistentes de IA e o KiCAD, permitindo controle em linguagem natural de operações de design de PCB.

Principais recursos:

146 ferramentas em 13 categorias com validação JSON Schema
Descoberta de ferramentas por palavra-chave via search_tools / get_category_tools
8 recursos dinâmicos expondo o estado do projeto
Fluxo de trabalho de esquemático completo com 27 ferramentas e carregamento dinâmico de símbolos (~10.000 símbolos)
Integração do roteador automático Freerouting (Java, Docker ou Podman)
Ferramentas personalizadas de footprint e criação de símbolos
Integração de peças JLCPCB com catálogo de 2,5M+ de componentes e busca em biblioteca local
Enriquecimento de datasheets via LCSC
Conformidade total com o protocolo MCP 2025-06-18
Suporte multiplataforma (Linux, Windows, macOS)
Integração em tempo real com a UI do KiCAD via API IPC (experimental)
Tratamento abrangente de erros e registro de logs

Experimente o Arduino MCP — agora você pode pedir ajuda ao Claude na IDE, em tempo real!:

https://github.com/mixelpixx/arduino-ide

O que há de novo na v2.6.0

Um bug que derrubava a sessão foi corrigido

Excluir qualquer coisa de uma placa — um componente, uma trilha, um contorno de placa — funcionava exatamente uma vez. A próxima operação, até mesmo uma leitura pura, falhava com um erro SwigPyObject, e apenas close_project seguido de open_project recuperava. O BOARD.Remove() transfere a propriedade do C++ para o Python, então soltar a referência executava um destrutor em um objeto ao qual o KiCad ainda apontava, corrompendo o estado do SWIG em todo o processo. Seis pontos de chamada foram afetados; todos agora usam BOARD.Delete().

10 novas ferramentas

Importação de PCB de fornecedores: import_pcb converte arquivos .brd de PADS, Altium, Eagle, CADSTAR, Fabmaster, P-CAD, SolidWorks PCB e Cadence Allegro binário via importador nativo do KiCad 10.
Esquemáticos hierárquicos: remove_hierarchical_sheet, set_sheet_property, get_sheet_properties e hierarchical_place para organizar footprints pela hierarquia do esquemático.
Lint e reparo de esquemáticos: lint_offgrid encontra e ajusta com segurança geometria fora da grade que silenciosamente quebra a colocação de junções; repair_flat_symbols corrige símbolos SnapEDA/SamacSys que travam o kicad-skip; lint_schematic_cosmetic organiza nomes de pinos e orientação de rótulos.
Origens da placa: set_board_origin / get_board_origin.

Suas classes de rede `.kicad_pro` não desaparecem mais

Salvamentos de placa não permitem mais que o pcbnew serialize um modelo de projeto desatualizado em memória sobre suas classes de rede editadas manualmente e o netclass_patterns. Abrir um projeto não reescreve mais o arquivo de forma alguma.

Quebra: ferramentas de esquemático falham ruidosamente em uma folha não analisável

Ferramentas que costumavam retornar resultados parciais ou vazios agora retornam um erro schematic_load_failed estruturado nomeando os símbolos problemáticos. Pular silenciosamente uma folha quebrada produzia um mapa incompleto de pad-para-rede relatado como sucesso, o que é pior. repair_flat_symbols corrige a causa usual. Veja KNOWN_ISSUES.md seção 7.

Detalhes completos no CHANGELOG.

O que há de novo na v2.5.0

20 novas ferramentas de ciclo de vida e geometria de placa

Ciclo de vida: open_board, reload_board, save_board, save_as, is_dirty, discard_or_reload, create_board_from_schematic.
Edição de gráficos: clear_board_outline, replace_board_outline, list_graphics, delete_graphic, update_graphic, move_footprint_text.
Consultas de geometria: batch_move_components, get_component_geometry, get_pads, get_net_pads, get_ratsnest, estimate_airwire_lengths, check_placement_clearance.

Todas respeitam o pinning de sessão do backend, então uma placa salva enquanto a GUI do KiCad possui a sessão roteia para a GUI em vez de escrever uma cópia desatualizada em memória — incluindo o caso estranho em que save_as muda a identidade da placa no meio da sessão.

Formatação normalizada e aplicada

pre-commit run --all-files (black, isort, prettier, flake8, mypy, eslint) agora é um gate real de CI, que é o que o CONTRIBUTING sempre afirmou.
npm run lint costumava executar black em modo write contra qualquer black que estivesse em PATH, reformatando silenciosamente sua árvore de trabalho com uma versão que discordava da CI. Agora ele apenas verifica; npm run format:py é o caminho de escrita.
A contagem de ferramentas do README é fixada ao registro por um teste, então ela se autocorrige em vez de divergir.

Detalhes completos no CHANGELOG.

O que há de novo na v2.4.1

Três ferramentas que eram registradas mas não tinham backend agora funcionam

assign_net_to_class, check_clearance e set_layer_constraints cada uma tinha um esquema completo e uma entrada de roteador, mas nenhum handler de despacho, então toda chamada retornava Unknown command. Encontrado por uma auditoria de cobertura de documentação.
Restrições por camada são escritas em um arquivo de regras personalizadas .kicad_dru com escopo de projeto, que kicad-cli pcb drc e a GUI ambos reconhecem — não há API pcbnew para elas.

Falhas silenciosas removidas

autoroute era abandonado pela ponte Node aos 30 s enquanto o Freerouting ainda estava em execução, relatando falha contra um .ses válido que existia no disco. Seu timeout agora deriva do timeout e attempts que você passa.
get_board_2d_view omitia --layers completamente quando nenhuma camada era fornecida, e o KiCad 9+ então recusa a exportação — não produzindo nenhum arquivo.
create_zone levantava AttributeError em toda chamada pelo backend IPC.

Novas ferramentas de fornecimento de peças

search_parts_registry / get_registry_part / download_registry_part reutilizam um footprint ou símbolo existente verificado em vez de gerar um novo. Downloads são permitidos por allowlist de host, verificados por extensão e limitados por tamanho.
get_jlcpcb_part retorna estoque ao vivo e preços por faixa quando as credenciais da Open Platform JLCPCB estão configuradas, caindo para o snapshot local.

CI agora realmente executa a suíte de testes

O job Python era um no-op em quatro formas independentes, e o Actions estava desabilitado em todo o repositório — 32 execuções falhas e 0 sucessos em toda a história do projeto. Todos os 1551 testes Python e 63 TypeScript agora bloqueiam cada push.

Detalhes completos no CHANGELOG.

O que há de novo na v2.4.0

Gerenciamento de bibliotecas de símbolos

import_symbol / export_symbol / rename_symbol copiam um símbolo entre bibliotecas .kicad_sym, extraem um para um arquivo independente e renomeiam um símbolo incluindo seus fragmentos de sub-símbolo e quaisquer referências (extends ...) de símbolos derivados na mesma biblioteca.
add_symbol_property e add_library_symbol_property definem campos BOM personalizados (Manufacturer, MPN, LCSC, ...) em um símbolo de biblioteca ou na definição em cache de um esquemático.
update_symbol_from_library atualiza definições lib_symbols em cache em um esquemático, uma lista ou cada projeto em um diretório — o equivalente programático do Atualizar Símbolo da Biblioteca do KiCad.
replace_instance_lib_ids troca referências lib_id conforme um mapeamento explícito de antigo-para-novo, para migrar um esquemático entre bibliotecas.

Descoberta de símbolos mais rápida

Diretórios de biblioteca, caminhos resolvidos, blocos de símbolos extraídos e listas de símbolos analisadas agora são armazenados em cache em todo o processo em vez de serem reconstruídos para cada adição de componente. Guardas de frescor revalidam caminhos e rastreiam o mtime_ns de origem, e os caminhos de escrita que mutam limpam os caches explicitamente.

Correções que restauram a operação básica

Cada .kicad_sym e escrita de esquemático levantava TypeError no Python 3.9, o piso declarado do projeto — Path.write_text não aceitava newline até 3.10.
A busca de peças JLCPCB não conseguia encontrar MPNs com hífen.
A importação do Eagle escrevia um cabeçalho de esquemático KiCad 9; agora escreve o cabeçalho KiCad 10, verificado contra kicad-cli 10.0 real.
A colocação de componentes se ajusta à grade de 1,27 mm, import_ses não cria mais redes fantasma sem barra, e export_dsn/autoroute mantêm classes de rede .kicad_pro.

Detalhes completos no CHANGELOG.

O que há de novo na v2.3.1

Importação de esquemáticos Eagle

import_eagle_schematic converte designs XML .sch do Eagle para o formato KiCad com mapeamento de símbolos, fios de rede, peças multi-gate, poda de fios pendentes e relatórios ERC de verdade fundamental via kicad-cli.

Ferramentas de modelos 3D e recarga interativa

add_component_3d_model / remove_component_3d_model para anexar modelos STEP/WRL a footprints.
KICAD_INTERACTIVE_SCHEMATIC=1 opcional confirma automaticamente o diálogo de recarga do KiCad no Windows após escritas de esquemático.

Cluster de scaffolding completo

Novos projetos começam em branco (nenhum símbolo _TEMPLATE_* vazou nos arquivos do usuário).
Arquivos .kicad_pro correspondem ao que o próprio KiCad escreve.
Versão de formato 20260101 garante que todas as builds 10.0.x do KiCad possam abrir esquemáticos gerados.

Compatibilidade com KiCad 10

Símbolos derivados em bibliotecas .kicad_symdir resolvem seu pai a partir de fragmentos irmãos.
Descoberta de instalação unificada encontra instalações Windows realocadas via registro.
Placeholders de variáveis de ambiente do usuário de kicad_common.json são resolvidos em caminhos de biblioteca.
Relatórios de pinos cruzando unidades fantasma em get_wire_connections são eliminados.

Detalhes completos no CHANGELOG.

O que há de novo na v2.3.0

Corrupção de esquemáticos no KiCad 10 — ambos os mecanismos corrigidos

Blocos de instância completos: componentes colocados agora carregam o nome real do projeto, caminho de uuid da folha raiz, entradas de uuid por pino (ERC pode vincular fios a pinos) e o conjunto completo de campos do KiCad 10 — verificado como byte-equivalente ao que o eeschema escreve. Antes, arrastar ou editar um símbolo colocado podia travar o KiCad.
Escritas multi-linha canônicas: ferramentas de esquemático não minificam mais o arquivo inteiro em uma linha. Escritas de ferramentas agora correspondem ao "Salvar" do eeschema byte por byte, com uma autoverificação em cada escrita que nunca pode corromper dados. Arquivos já minificados são reparáveis com scripts/kicad_sch_reformat.py.

Suas edições estão protegidas

Pinning de sessão de backend: um projeto carregado permanece em um backend (SWIG ou IPC) por todo o seu ciclo de vida — salvamentos não podem mais ser roteados silenciosamente para uma placa de GUI desatualizada e perder suas edições.
Guarda de edição externa: save_project se recusa a sobrescrever um arquivo de placa cujo conteúdo mudou no disco desde o carregamento (passe force: true para ignorar).
close_project (nova ferramenta): libere o projeto para que os arquivos possam ser editados diretamente e depois reabra — sem mais coreografia de reinicialização.

Funciona em uma instalação Windows padrão

kicad-cli e 7-Zip são resolvidos de seus locais de instalação mesmo quando não estão no PATH — desquebrando exportações, ERC/DRC, netlists, visualizações de placa e o download do banco de dados JLCPCB, cada um com erros acionáveis quando verdadeiramente ausentes.

Novas ferramentas de layout

suggest_placement: otimizador de posicionamento de PCB orientado por conectividade (dry-run por padrão, determinístico).
suggest_schematic_declutter: reorienta rótulos de rede sobrepostos sem tocar na conectividade. Além disso, correções de compatibilidade com KiCad 10 (renomeações de folhas, bibliotecas fragmentadas .kicad_symdir, tamanho de placa IPC Box2), geometria correta de pinos para símbolos rotacionados+espelhados e de múltiplas unidades, conexões IPC limitadas com fallback SWIG e uma suíte Vitest real para a camada TypeScript. Detalhes completos no CHANGELOG.

Novidades na v2.2.3

Novas Ferramentas: Fluxo de Trabalho de Passagem de Cabo FFC/Fita

Agora é suportado um fluxo de trabalho completo para projetar placas adaptadoras de passagem (por exemplo, adaptadores de cabo CSI do Raspberry Pi):

connect_passthrough — conecta todos os pinos de um conector aos pinos correspondentes de outro no esquemático (pino J1 N → pino J2 N, redes com nome automático).
sync_schematic_to_board — importa as atribuições de rede para o PCB.
route_pad_to_pad — roteia cada conexão com inserção automática de via quando as ilhas estão em camadas de cobre opostas.
snapshot_project — salva um checkpoint nomeado em <project>/snapshots/.

Correções de Bugs (KiCAD 9 / Windows)

Inserção de via para footprints em B.Cu — route_pad_to_pad agora detecta corretamente quando um footprint está em B.Cu e insere a via necessária. (O SWIG do KiCAD 9 retornava F.Cu para todas as ilhas SMD independentemente da camada — corrigido.)
Cantos arredondados do contorno da placa — add_board_outline agora aplica corretamente cornerRadius quando shape="rounded_rectangle".
Travamento na colocação em B.Cu — colocar um footprint em B.Cu não causa mais um congelamento de ~30s no KiCAD 9.

Modo Desenvolvedor

Defina KICAD_MCP_DEV=1 no ambiente MCP do Claude Desktop para salvar automaticamente o log da sessão MCP na pasta logs/ do projeto a cada chamada de export_gerber e snapshot_project. Útil para depuração e para anexar a problemas do GitHub.

"env": {
  "KICAD_MCP_DEV": "1"
}

Aviso de privacidade: O log da sessão contém todo o histórico de chamadas de ferramentas (incluindo caminhos de arquivos e detalhes de design). Revise ou exclua logs/ antes de compartilhar um diretório de projeto publicamente.

Veja o CHANGELOG para a lista completa de mudanças nesta versão.

Novidades na v2.1.0

Correção Crítica no Fluxo de Trabalho Esquemático + Sistema de Fiação Completo (Issue #26)

O fluxo de trabalho esquemático estava completamente quebrado nas versões anteriores - agora isso está corrigido E dramaticamente aprimorado!

O que estava quebrado:

create_project apenas criava arquivos PCB, sem esquemáticos
add_schematic_component chamava métodos de API inexistentes
Esquemáticos não podiam ser criados ou editados de forma alguma
Apenas 13 tipos de componentes disponíveis (limitação severa)
Nenhuma funcionalidade de fio/conexão funcionando

Implementação Completa (3 Fases):

Fase 1: Fundação de Posicionamento de Componentes

create_project agora cria tanto arquivos .kicad_pcb quanto .kicad_sch
Adicionados esquemáticos de modelo pré-configurados com 13 tipos comuns de componentes
Reescrito o posicionamento de componentes para usar a API adequada clone()

Fase 2: Carregamento Dinâmico de Símbolos (AVANÇO!)

Acesso a TODOS os ~10.000 símbolos KiCad das bibliotecas padrão
Detecção automática e carregamento dinâmico de arquivos de biblioteca .kicad_sym
Nenhuma configuração necessária - basta especificar biblioteca e nome do símbolo
Integração perfeita com as ferramentas MCP existentes
Sistema completo de análise e injeção de expressões S

Fase 3: Sistema de Fiação Inteligente (NOVO na v2.1.0)

Descoberta automática de localização de pinos com suporte a rotação (0°, 90°, 180°, 270°)
Roteamento inteligente de fios (direto, ortogonal horizontal primeiro, ortogonal vertical primeiro)
Suporte a símbolos de alimentação (VCC, GND, +3V3, +5V, etc.)
Análise de grafo de fios - rastreamento geométrico para conectividade de rede
Gerenciamento de rótulos de rede (rótulos locais, globais, hierárquicos)
Geração de netlist com conexões precisas de componentes/pinos

Arquitetura Técnica:

A biblioteca kicad-skip não pode criar símbolos ou fios do zero. Implementamos uma solução abrangente:

Modelos Estáticos: 13 símbolos pré-configurados (R, C, L, LED, etc.) para uso imediato
Carregamento Dinâmico: Injeção sob demanda de QUALQUER símbolo das bibliotecas KiCad:
- Analisar arquivos de biblioteca .kicad_sym usando o analisador de expressões S
- Injetar a definição do símbolo na seção lib_symbols do esquemático
- Criar instância de modelo fora da tela
- Recarregar o esquemático para que o kicad-skip veja o novo modelo
- Clonar o modelo para criar o componente real
Criação de Fios: Injeção de fios baseada em expressões S (contorna as limitações da API do kicad-skip)
Descoberta de Pinos: Analisar definições de símbolos, aplicar transformações de rotação, calcular posições absolutas
Análise de Conectividade: Rastreamento geométrico de fios para construir grafos de conexão de rede

Exemplo - Criação de Circuito Completo:

# Load power symbols dynamically
loader.load_symbol_dynamically(sch_path, "power", "VCC")

# Place components with auto-rotation
ComponentManager.add_component(sch, {
    "type": "STM32F103C8Tx",
    "library": "MCU_ST_STM32F1",
    "reference": "U1",
    "x": 100, "y": 100, "rotation": 0
})

# Connect with intelligent routing
ConnectionManager.add_connection(sch_path, "U1", "1", "R1", "2", routing="orthogonal_h")

# Connect to power nets
ConnectionManager.connect_to_net(sch_path, "U1", "VDD", "VCC")

# Analyze connectivity
connections = ConnectionManager.get_net_connections(sch, "VCC", sch_path)
# Returns: [{"component": "U1", "pin": "VDD"}, {"component": "R1", "pin": "1"}]

Resultados dos Testes:

Posicionamento de componentes: 100% passando
Carregamento dinâmico de símbolos: mais de 10.000 símbolos acessíveis
Criação de fios: 100% passando (8/8 conexões no circuito de teste)
Descoberta de pinos: ciente de rotação, precisão submilimétrica
Conectividade de rede: 100% precisa (VCC: 2 conexões, GND: 4 conexões)
Geração de netlist: Funcionando com conexões precisas em nível de pino

Veja a Referência de Ferramentas Esquemáticas para a documentação completa das ferramentas esquemáticas, e o Guia de Autoria Headless para práticas testadas em campo ao usar essas ferramentas sem a GUI do KiCad.

Backend IPC (Experimental)

Atualmente estamos implementando e testando a API IPC do KiCAD 9.0 para sincronização de UI em tempo real:

Alterações feitas via ferramentas MCP aparecem imediatamente na UI do KiCAD
Nenhum recarregamento manual necessário quando o IPC está ativo
Backend híbrido: usa IPC quando disponível, recorre à API SWIG
Reconexão em tempo de execução do IPC: se o MCP recorreu ao SWIG, as ferramentas de placa com capacidade IPC tentam o IPC novamente após o KiCAD iniciar, em vez de permanecer no SWIG durante toda a sessão
Mais de 20 comandos agora suportam IPC, incluindo roteamento, posicionamento de componentes e operações de zona

Nota: Os recursos IPC estão em desenvolvimento e teste ativos. Habilite o IPC no KiCAD via Preferências > Plugins > Ativar Servidor de API IPC.

Para OpenCode no Windows, o backend pode ser configurado como auto, ipc ou swig durante a configuração. Veja OpenCode (Windows) para o comando de configuração e opções de backend.

Padrão de Descoberta de Ferramentas e Roteador

Implementamos um roteador inteligente de ferramentas para manter o contexto da IA eficiente enquanto mantém a funcionalidade completa:

22 ferramentas diretas sempre visíveis para operações de alta frequência
111 ferramentas roteadas organizadas em 13 categorias (board, component, export, drc, schematic, library, symbol_pins, schematic_hierarchy, schematic_layout, schematic_batch, routing, autoroute, parts-registry)
4 ferramentas de roteador para descoberta e execução:
- list_tool_categories - Navegar por todas as categorias disponíveis
- get_category_tools - Ver ferramentas em uma categoria específica
- search_tools - Encontrar ferramentas por palavra-chave
- execute_tool - Executar qualquer ferramenta com parâmetros

Por que isso importa: Ao organizar as ferramentas em categorias descobríveis, o Claude pode encontrar e usar inteligentemente a ferramenta certa para sua tarefa sem carregar todos os 122 esquemas de ferramentas em cada conversa. Isso reduz o consumo de contexto enquanto mantém acesso total a toda a funcionalidade.

O uso é perfeito: Basta pedir naturalmente - "exportar arquivos gerber" ou "adicionar furos de montagem" - e o Claude descobrirá e executará as ferramentas apropriadas automaticamente.

PRECISA DE TESTES - RELATE PROBLEMAS

Integração de Peças JLCPCB (Novo!)

Integração completa com o catálogo de peças da JLCPCB, fornecendo duas abordagens complementares para seleção de componentes:

Arquitetura de Modo Duplo:

Bibliotecas de Símbolos Locais - Pesquise bibliotecas JLCPCB instaladas via Plugin e Gerenciador de Conteúdo do KiCAD (contribuído por @l3wi)
Integração com API JLCPCB - Acesse o catálogo completo de mais de 2,5 milhões de peças com preços em tempo real e dados de estoque

Principais Recursos:

Preços em tempo real com faixas de quantidade (1+, 10+, 100+, 1000+)
Verificação de disponibilidade de estoque
Identificação do tipo de biblioteca Básica vs Estendida (Básica = montagem gratuita)
Otimização inteligente de custos com sugestões de peças alternativas
Mapeamento de pacote para footprint para compatibilidade com KiCAD
Pesquisa paramétrica por categoria, pacote, fabricante
Banco de dados SQLite local para pesquisa offline rápida
Nenhuma credencial de API necessária para pesquisa em biblioteca local

Por que isso importa: A JLCPCB oferece serviços de montagem de PCB onde peças Básicas não têm taxa de montagem, enquanto peças Estendidas cobram $3 por componente único. Essa integração ajuda você a encontrar os componentes mais baratos com a melhor disponibilidade, potencialmente economizando centenas de dólares em custos de montagem para execuções de produção.

Veja o Guia de Uso JLCPCB para instruções detalhadas de configuração e uso.

Esquemas Abrangentes de Ferramentas

Cada ferramenta agora inclui definições completas de JSON Schema com:

Descrições detalhadas de parâmetros e restrições
Validação de entrada com verificação de tipo
Especificações de parâmetros obrigatórios vs. opcionais
Valores enumerados para entradas categóricas
Documentação clara do que cada ferramenta faz

Capacidade de Recursos

Acesse o estado do projeto sem executar ferramentas:

kicad://project/current/info - Metadados do projeto
kicad://project/current/board - Propriedades da placa
kicad://project/current/components - Lista de componentes (JSON)
kicad://project/current/nets - Redes elétricas
kicad://project/current/layers - Configuração da pilha de camadas
kicad://project/current/design-rules - Configurações atuais de DRC
kicad://project/current/drc-report - Violações de regras de design
kicad://board/preview.png - Visualização da placa (PNG)

Conformidade com Protocolo

Atualizado para MCP SDK 1.21.0 (mais recente)
Suporte completo a JSON-RPC 2.0
Negociação adequada de capacidades
Códigos de erro em conformidade com padrões

Ferramentas Disponíveis

O servidor expõe todas as ferramentas diretamente, para que seu assistente possa chamar qualquer uma delas sem uma etapa de descoberta - basta pedir o que você deseja realizar. 146 ferramentas são adicionalmente indexadas em 13 categorias funcionais, para que search_tools e get_category_tools possam encontrar uma por palavra-chave.

Para a referência completa de ferramentas com tipos de acesso (direta/roteada/adicional), veja o Inventário de Ferramentas.

Gerenciamento de Projeto (5 ferramentas)

create_project - Inicializar novos projetos KiCAD
open_project - Carregar arquivos de projeto existentes
save_project - Salvar o estado atual do projeto
get_project_info - Recuperar metadados do projeto
snapshot_project - Salvar snapshot de checkpoint nomeado

Operações de Placa (12 ferramentas)

set_board_size - Configurar dimensões do PCB
add_board_outline - Criar borda da placa (retângulo, círculo, polígono, retângulo arredondado)
add_layer - Adicionar camadas personalizadas à pilha
set_active_layer - Alternar camada de trabalho
get_layer_list - Listar todas as camadas da placa
get_board_info - Recuperar propriedades da placa
get_board_2d_view - Gerar imagem de pré-visualização da placa
get_board_extents - Obter caixa delimitadora da placa
add_mounting_hole - Colocar furos de montagem
add_board_text - Adicionar anotações de texto
add_zone - Adicionar zona/preenchimento de cobre com configurações de folga
import_svg_logo - Importar arquivo SVG como polígonos de serigrafia do PCB

Gerenciamento de Componentes (16 ferramentas)

place_component - Colocar componente único com footprint
move_component - Reposicionar componente existente
rotate_component - Rotacionar componente por ângulo
delete_component - Remover componente da placa
edit_component - Modificar propriedades do componente
find_component - Pesquisar por referência ou valor
get_component_properties - Consultar detalhes do componente
add_component_annotation - Adicionar anotação/comentário
group_components - Agrupar múltiplos componentes
replace_component - Substituir por footprint diferente
get_component_pads - Obter todas as informações de ilhas
get_component_list - Listar todos os componentes colocados
get_pad_position - Obter posição precisa da ilha
place_component_array - Criar grades/padrões de componentes
align_components - Alinhar múltiplos componentes
duplicate_component - Copiar componente existente

Roteamento (13 ferramentas)

add_net - Criar net elétrica
route_trace - Roteamento de trilhas de cobre entre pontos XY
route_pad_to_pad - Roteamento entre pads com inserção automática de vias
add_via - Colocar vias para transições de camada
delete_trace - Remover trilhas (por UUID, posição ou net)
query_traces - Consultar/filtrar trilhas
get_nets_list - Listar todas as nets com estatísticas
modify_trace - Alterar largura da trilha, camada ou net
create_netclass - Definir classe de net com regras
add_copper_pour - Criar zonas de cobre/preenchimentos
route_differential_pair - Roteamento de sinais diferenciais
refill_zones - Reabastecer todas as zonas de cobre
copy_routing_pattern - Replicar roteamento entre grupos de componentes

Esquemático (27 ferramentas)

Fluxo de trabalho completo de esquemático com carregamento dinâmico de símbolos (~10.000 símbolos) e fiação inteligente.

Operações de Componentes:

add_schematic_component - Colocar símbolos de qualquer biblioteca KiCad
delete_schematic_component - Remover componente
edit_schematic_component - Editar footprint, valor, referência, posições de rótulo e propriedades personalizadas arbitrárias (MPN, Fabricante, DigiKey_PN, LCSC, Tensão, Tolerância, Dielétrico, …) em uma única chamada em lote
set_schematic_component_property - Adicionar ou atualizar uma única propriedade personalizada (campo de BOM/fornecimento) em um componente
remove_schematic_component_property - Excluir uma única propriedade personalizada de um componente
get_schematic_component - Inspecionar todos os campos de um componente (integrados + personalizados) incluindo posições de rótulo
list_schematic_components - Listar todos os componentes
move_schematic_component - Reposicionar componente
rotate_schematic_component - Girar componente
annotate_schematic - Atribuir automaticamente designadores de referência

Fiação e Conexões:

add_wire - Criar fio entre pontos
delete_schematic_wire - Remover segmento de fio
add_schematic_connection - Conectar pinos automaticamente com roteamento
add_schematic_net_label - Adicionar rótulos de net (VCC, GND, sinais)
delete_schematic_net_label - Remover rótulo de net
connect_to_net - Conectar pino a net nomeada
connect_passthrough - Conectar todos os pinos correspondentes entre conectores (FFC/fita)
get_schematic_pin_locations - Obter localizações de pinos para componente

Análise e Exportação:

get_net_connections - Rastrear conectividade de net
list_schematic_nets / list_schematic_wires / list_schematic_labels
create_schematic - Criar novo arquivo de esquemático
get_schematic_view - Visualização rasterizada do esquemático
export_schematic_svg / export_schematic_pdf
run_erc - Verificação de regras elétricas
generate_netlist - Gerar netlist a partir do esquemático
sync_schematic_to_board - Importar nets/pads para o PCB (equivalente a F8)

Consulte Referência de Ferramentas de Esquemático para detalhes e exemplos.

Regras de Design / DRC (8 ferramentas)

set_design_rules / get_design_rules - Configurar e inspecionar regras
run_drc - Executar verificação de regras de design
get_drc_violations - Obter lista de violações por gravidade
create_netclass / assign_net_to_class - Gerenciamento de classes de net
set_layer_constraints / check_clearance - Regras de camada e folga

Exportação (8 ferramentas)

export_gerber - Arquivos de fabricação Gerber
export_pdf / export_svg - Documentação e gráficos vetoriais
export_3d - Modelos 3D (STEP, STL, VRML, OBJ)
export_bom - Lista de materiais (CSV, XML, HTML, JSON)
export_netlist - Netlist (KiCad, Spice, Cadstar, OrcadPCB2)
export_position_file - Posições de componentes para pick and place
export_vrml - Modelo 3D VRML

Bibliotecas de Footprint (4 ferramentas) e Bibliotecas de Símbolos (4 ferramentas)

list_libraries / list_symbol_libraries - Navegar pelas bibliotecas disponíveis
search_footprints / search_symbols - Pesquisar em todas as bibliotecas
list_library_footprints / list_library_symbols - Navegar por biblioteca específica
get_footprint_info / get_symbol_info - Informações detalhadas

Criador de Footprint (4 ferramentas) e Criador de Símbolos (4 ferramentas)

Crie componentes personalizados quando as bibliotecas existentes não tiverem o que você precisa.

create_footprint / create_symbol - Construir do zero com pads/pinos
edit_footprint_pad - Modificar propriedades de pad
register_footprint_library / register_symbol_library - Registrar na tabela de bibliotecas
list_footprint_libraries / list_symbols_in_library - Navegar por bibliotecas personalizadas
delete_symbol - Remover símbolo da biblioteca

Consulte Guia do Criador de Footprint e Símbolos para detalhes.

Ferramentas de Datasheet (2 ferramentas)

enrich_datasheets - Preencher automaticamente URLs de datasheet usando números de peça LCSC
get_datasheet_url - Obter URL de datasheet LCSC para um componente

Integração JLCPCB (5 ferramentas)

download_jlcpcb_database - Baixar catálogo de peças 2,5M+ (configuração única)
search_jlcpcb_parts - Pesquisar com filtros paramétricos
get_jlcpcb_part - Informações detalhadas da peça com preços
get_jlcpcb_database_stats - Estatísticas do banco de dados
suggest_jlcpcb_alternatives - Encontrar alternativas mais baratas ou em estoque

Autorouter Freerouting (4 ferramentas)

autoroute - Executar autorouter Freerouting (exportação DSN, roteamento, importação SES)
export_dsn / import_ses - Fluxo de trabalho manual Specctra DSN/SES
check_freerouting - Verificar disponibilidade de Java e Freerouting

Consulte Guia Freerouting para configuração e uso.

Gerenciamento de UI (2 ferramentas)

check_kicad_ui - Verificar se o KiCAD está em execução
launch_kicad_ui - Iniciar aplicativo KiCAD

Pré-requisitos

Software Necessário

KiCAD 9.0 ou superior

Baixe de kicad.org/download
Deve incluir o módulo Python (pcbnew)

Verifique a instalação:

python3 -c "import pcbnew; print(pcbnew.GetBuildVersion())"

Node.js 18 ou superior

Baixe de nodejs.org
Verifique: node --version e npm --version

Python 3.9 ou superior

Vem incluído com o KiCAD (as versões macOS incluem Python 3.9; as versões Linux/Windows incluem Python 3.11)
Pacotes necessários (instalados automaticamente):
- kicad-python (kipy) >= 0.5.0 (suporte à API IPC, opcional, mas recomendado)
- kicad-skip >= 0.1.0 (suporte a esquemáticos)
- Pillow >= 9.0.0 (processamento de imagens)
- cairosvg >= 2.7.0 (renderização SVG)
- colorlog >= 6.7.0 (registro de logs)
- pydantic >= 2.5.0 (validação)
- requests >= 2.32.5 (cliente HTTP)
- python-dotenv >= 1.0.0 (ambiente)

Cliente MCP

Escolha um:

Claude Desktop - Aplicativo de desktop oficial da Anthropic
Claude Code - Ferramenta CLI oficial
Cline - Extensão do VSCode
OpenCode - Agente de codificação de IA baseado em terminal com suporte a MCP

Plataformas Suportadas

Linux (Ubuntu 22.04+, Fedora, Arch) - Plataforma principal, totalmente testada
Windows 10/11 - Totalmente suportado com configuração automatizada
macOS - Suporte experimental

Instalação

Linux (Ubuntu/Debian)

# Install KiCAD 9.0 or higher
sudo add-apt-repository --yes ppa:kicad/kicad-9.0-releases
sudo apt-get update
sudo apt-get install -y kicad kicad-libraries

# Install Node.js
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Clone and build
git clone https://github.com/mixelpixx/KiCAD-MCP-Server.git
cd KiCAD-MCP-Server
npm install
pip3 install -r requirements.txt
npm run build

# Verify
python3 -c "import pcbnew; print(pcbnew.GetBuildVersion())"

Windows 10/11

Configuração Automatizada (Recomendada):

git clone https://github.com/mixelpixx/KiCAD-MCP-Server.git
cd KiCAD-MCP-Server
.\setup-windows.ps1

O script irá:

Detectar instalações do KiCAD, incluindo instalações em toda a máquina em C:\Program Files\KiCad e instalações por usuário em %LOCALAPPDATA%\Programs\KiCad
Verificar pré-requisitos
Instalar dependências
Compilar o projeto
Gerar configuração
Executar diagnósticos

Configuração Manual: Consulte Guia de Instalação do Windows para instruções detalhadas.

macOS

Importante: No macOS, use o Python incluído no KiCAD para garantir acesso adequado ao módulo pcbnew.

Configuração Manual

# Install KiCAD 9.0 from kicad.org/download/macos

# Install Node.js
brew install node@20

# Clone repository
git clone https://github.com/mixelpixx/KiCAD-MCP-Server.git
cd KiCAD-MCP-Server

# Create virtual environment using KiCAD's bundled Python
/Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/Current/bin/python3 -m venv venv --system-site-packages

# Activate virtual environment
source venv/bin/activate

# Install dependencies
npm install
pip install -r requirements.txt
npm run build

Nota: A flag --system-site-packages é necessária para acessar o módulo pcbnew do KiCAD a partir do ambiente virtual.

Configuração Automatizada

Para simplificar a configuração com o Claude Desktop, este repositório fornece um script de configuração para macOS:

./setup-macos.sh

Em caso de erro zsh: permission denied: ./setup-macos.sh, você pode:

sempre permitir que o script seja executado executando: chmod +x setup-macos.sh.
alternativamente, execute-o explicitamente com bash: bash setup-macos.sh para que não seja necessária alteração de chmod.

Este script não substitui a configuração manual acima — ele assume que as dependências já estão instaladas e o projeto está compilado. Em vez disso, ele automatiza:

detecção do seu ambiente (Node.js, Python do KiCad, pcbnew)
resolução do PYTHONPATH correto do macOS
geração da configuração MCP correta do Claude Desktop
mesclagem segura da configuração na sua configuração existente do Claude
opcionalmente, gravação da configuração com suporte a backup

Uso Básico

Verificar configuração (sem alterações)

./setup-macos.sh --verify

Visualizar configuração (teste seco)

./setup-macos.sh --dry-run

Aplicar configuração

./setup-macos.sh --apply

Após aplicar, reinicie o Claude Desktop.

Parâmetros

Parâmetros obrigatórios

Nenhum. O script funciona imediatamente usando padrões sensatos.

Parâmetros opcionais

`--name NAME`

Especifique o nome do servidor MCP no Claude Desktop.

Padrão:

kicad

Exemplo:

./setup-macos.sh --apply --name kicad-dev

Use isso quando:

executando múltiplas configurações MCP
testando forks ou versões de desenvolvimento
evitando sobrescrever uma configuração existente

`--claude-config PATH`

Especifique um arquivo de configuração personalizado do Claude Desktop.

Padrão:

~/Library/Application Support/Claude/claude_desktop_config.json

Exemplo:

./setup-macos.sh --dry-run --claude-config ~/tmp/claude_config.json

Use isso quando:

testando configurações com segurança
usando locais de configuração não padrão
depurando sem modificar sua configuração principal

`--yes`

Pular o prompt de confirmação ao aplicar alterações.

Exemplo:

./setup-macos.sh --apply --yes

Após a Configuração

Saia completamente do Claude Desktop
Reabra o Claude Desktop
Abra um novo chat
Clique em + → Conectores
Verifique se o servidor aparece (por exemplo, kicad ou seu nome personalizado)

Teste com o prompt no Claude Desktop:

Use the kicad MCP server to run check_kicad_ui.

Notas

O script modifica apenas a seção mcpServers e deixa toda a outra configuração intacta
As configurações existentes são automaticamente copiadas antes das alterações
O suporte ao macOS depende do Python incluído no KiCad; o Python do sistema não funcionará corretamente
Se o KiCad for atualizado ou movido, execute o script novamente para atualizar os caminhos

Configuração

Claude Desktop

Edite o arquivo de configuração:

Linux: ~/.config/Claude/claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Configuração:

{
  "mcpServers": {
    "kicad": {
      "command": "node",
      "args": ["/path/to/KiCAD-MCP-Server/dist/index.js"],
      "env": {
        "PYTHONPATH": "/path/to/kicad/python",
        "LOG_LEVEL": "info"
      }
    }
  }
}

PYTHONPATH específico da plataforma:

Linux: /usr/lib/kicad/lib/python3/dist-packages
Windows: C:\Program Files\KiCad\10.0\lib\python3\dist-packages ou %LOCALAPPDATA%\Programs\KiCad\10.0\lib\python3\dist-packages
macOS: /Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/3.9/lib/python3.9/site-packages

Detecção de Python no Linux

O servidor detecta automaticamente o Python no Linux nesta ordem de prioridade:

Ambiente virtual - venv/bin/python ou .venv/bin/python (prioridade mais alta)
Variável de ambiente KICAD_PYTHON - Substituição do usuário para instalações não padrão
Python incluído no KiCad - /usr/lib/kicad/bin/python3, /usr/local/lib/kicad/bin/python3, /opt/kicad/bin/python3
Python do sistema via which - Resolve which python3 para caminho absoluto (por exemplo, /usr/bin/python3)
Caminhos comuns do sistema - /usr/bin/python3, /bin/python3

Para a maioria das instalações Linux padrão (Ubuntu, Debian, Fedora, Arch), nenhuma configuração KICAD_PYTHON é necessária - o servidor encontrará automaticamente sua instalação do Python.

Solução de problemas:

Se você vir "Python executable not found: python3", você pode especificar manualmente o caminho do Python:

{
  "mcpServers": {
    "kicad": {
      "command": "node",
      "args": ["/path/to/KiCAD-MCP-Server/dist/index.js"],
      "env": {
        "KICAD_PYTHON": "/usr/bin/python3",
        "PYTHONPATH": "/usr/lib/kicad/lib/python3/dist-packages"
      }
    }
  }
}

Para encontrar seu caminho do Python:

which python3  # Example output: /usr/bin/python3
python3 -c "import pcbnew; print(pcbnew.GetBuildVersion())"  # Verify pcbnew access

GitHub Copilot (VS Code)

Copie o modelo para seu espaço de trabalho:

cp config/vscode-mcp.example.json .vscode/mcp.json

O VS Code detectará automaticamente .vscode/mcp.json e registrará o servidor. O modelo usa ${workspaceFolder}, portanto, não é necessário editar caminhos.

Nota: .vscode/mcp.json está listado em .gitignore — sua configuração local não será commitada.

Cline (VSCode)

Edite: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Use o mesmo formato de configuração do Claude Desktop acima.

Claude Code

O Claude Code detecta automaticamente servidores MCP no diretório atual. Nenhuma configuração adicional é necessária.

OpenCode (Windows)

O OpenCode usa um esquema de configuração MCP diferente do Claude Desktop. Use setup-windows-opencode.ps1 para verificar a configuração local e escrever a entrada correta do OpenCode mcp.

A configuração do projeto OpenCode é gravada em opencode.json na raiz do projeto de destino. O script mantém o repositório do servidor MCP KiCAD separado do projeto de destino:

McpServerPath é este repositório, onde dist/index.js é compilado
ProjectPath é o projeto que deve receber opencode.json

Quando isso é útil:

Você usa OpenCode como seu cliente MCP no Windows
Você quer um servidor MCP local ao projeto, disponível apenas em um projeto
Você quer um servidor MCP global do OpenCode disponível em qualquer espaço de trabalho
Você precisa verificar o Python do KiCAD (pcbnew), o Node.js e dist/index.js antes de alterar a configuração do OpenCode

Seleção de backend

O script de configuração suporta três preferências de backend do KiCAD via -Backend:

auto — tenta IPC primeiro e usa SWIG como fallback se IPC estiver indisponível (padrão)
ipc — exige IPC do KiCAD para sincronização de UI em tempo real
swig — usa o backend baseado em arquivo pcbnew

Exemplos:

.\setup-windows-opencode.ps1 -Apply -Scope project -Backend auto
.\setup-windows-opencode.ps1 -Apply -Scope project -Backend ipc
.\setup-windows-opencode.ps1 -Apply -Scope project -Backend swig

Para -Backend ipc, o KiCAD deve estar em execução com o servidor da API IPC habilitado.

Verificar a configuração sem alterações

Use esta opção primeiro ao diagnosticar problemas de instalação ou de caminho. Ela detecta o KiCAD, testa pcbnew, verifica o Node.js e valida o ponto de entrada MCP compilado.

.\setup-windows-opencode.ps1 -Verify -SkipInstall -SkipBuild

Visualizar a configuração do OpenCode

Use o modo dry run quando quiser inspecionar o JSON exato antes de gravá-lo.

.\setup-windows-opencode.ps1 -DryRun -SkipInstall -SkipBuild

Exemplo do formato gerado do OpenCode:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "kicad": {
      "type": "local",
      "command": ["node", "C:\\path\\to\\KiCAD-MCP-Server\\dist\\index.js"],
      "environment": {
        "NODE_ENV": "production",
        "LOG_LEVEL": "info",
        "KICAD_AUTO_LAUNCH": "false",
        "KICAD_MCP_DEV": "0",
        "KICAD_BACKEND": "auto",
        "PYTHONPATH": "C:\\Program Files\\KiCad\\10.0\\bin\\Lib\\site-packages"
      },
      "enabled": true,
      "timeout": 30000
    }
  }
}

Um modelo copiável também é fornecido em config/opencode.json. Substitua os caminhos de espaço reservado antes de usá-lo diretamente.

Aplicar configuração local ao projeto

Use esta opção quando quiser que o MCP do KiCAD seja habilitado apenas para um projeto. O script grava opencode.json na raiz do projeto de destino e faz backup de um arquivo existente antes de alterá-lo.

.\setup-windows-opencode.ps1 -Apply -Scope project

Por padrão, ProjectPath é o diretório de trabalho atual.

Para configurar outro projeto, passe -ProjectPath:

.\setup-windows-opencode.ps1 -Apply -Scope project -ProjectPath "C:\path\to\your-project"

Se o script de configuração não estiver localizado no repositório do KiCAD MCP Server, passe -McpServerPath para que a configuração gerada aponte para o dist/index.js correto:

.\setup-windows-opencode.ps1 `
  -Apply `
  -Scope project `
  -ProjectPath "C:\path\to\your-project" `
  -McpServerPath "C:\path\to\KiCAD-MCP-Server"

Aplicar configuração global do OpenCode

Use esta opção quando quiser que o servidor MCP do KiCAD esteja disponível em qualquer espaço de trabalho do OpenCode. O script grava %USERPROFILE%\.config\opencode\opencode.json.

.\setup-windows-opencode.ps1 -Apply -Scope global

Usar um nome de servidor MCP personalizado

Use esta opção ao testar múltiplos forks ou manter entradas MCP do KiCAD separadas de desenvolvimento e estáveis.

.\setup-windows-opencode.ps1 -Apply -Scope project -Name kicad-dev

Usar um caminho de instalação personalizado do KiCAD

Use esta opção quando o KiCAD estiver instalado fora dos locais padrão do Windows.

.\setup-windows-opencode.ps1 -Apply -Scope project -KiCadRoot "D:\Apps\KiCad\10.0"

Pular etapas de instalação ou compilação

Use estas flags quando as dependências já estiverem instaladas ou o projeto já estiver compilado.

.\setup-windows-opencode.ps1 -Apply -Scope project -SkipInstall -SkipBuild

Após aplicar a configuração

Feche completamente o OpenCode.
Inicie o OpenCode novamente para que ele recarregue opencode.json.
Peça ao OpenCode para usar o servidor MCP kicad e execute check_kicad_ui.

Desabilitar o servidor MCP do OpenCode

Para desabilitar o servidor sem remover a configuração completa, defina a entrada como enabled: false e reinicie o OpenCode.

{
  "mcp": {
    "kicad": {
      "enabled": false
    }
  }
}

Se o OpenCode estiver em execução, o processo do servidor MCP é gerenciado pelo OpenCode e normalmente é encerrado quando o OpenCode sai.

Configuração da Integração JLCPCB (Opcional)

A integração JLCPCB oferece dois modos que podem ser usados de forma independente ou combinada:

Modo 1: API Pública JLCSearch (Recomendado — Sem Configuração Necessária)

A forma mais fácil de acessar o catálogo de componentes da JLCPCB:

Nenhuma credencial de API necessária
Nenhuma conta JLCPCB necessária
Acesso a mais de 2,5 milhões de componentes com dados de preço e estoque
Tempo de download: 40–60 minutos para o catálogo completo (lotes de 100 componentes devido ao limite da API)

Para baixar o banco de dados:

Ask Claude: "Download the JLCPCB parts database"

Isso cria um banco de dados SQLite local em data/jlcpcb_parts.db (3–5 GB para o catálogo completo de 2,5 milhões de componentes).

Modo 2: Bibliotecas Locais de Símbolos (Sem Configuração Necessária)

Instale as bibliotecas JLCPCB via Gerenciador de Plugins e Conteúdo do KiCAD:

Abra o KiCAD
Vá em Ferramentas > Gerenciador de Plugins e Conteúdo
Pesquise por "JLCPCB" ou "JLC"
Instale bibliotecas como JLCPCB-KiCAD-Library ou EDA_MCP
Use search_symbols para encontrar componentes com footprints pré-configurados e IDs LCSC

Modo 3: API Oficial da JLCPCB (Avançado — Requer Conta Empresarial)

Para usuários com contas empresariais JLCPCB e histórico de pedidos:

Obter Credenciais da API
- Faça login em JLCPCB
- Navegue até Conta > Gerenciamento de API (requer aprovação empresarial)
- Crie uma chave de API e salve seu appKey e appSecret
- Observação: Isso requer histórico prévio de pedidos e aprovação de conta empresarial

Configurar Variáveis de Ambiente

Adicione ao seu perfil de shell (~/.bashrc, ~/.zshrc ou ~/.profile):

export JLCPCB_API_KEY="your_app_key_here"
export JLCPCB_API_SECRET="your_app_secret_here"

Ou crie um arquivo .env na raiz do projeto:

JLCPCB_API_KEY=your_app_key_here
JLCPCB_API_SECRET=your_app_secret_here

Veja o Guia de Uso do JLCPCB para documentação detalhada.

Exemplos de Uso

Fluxo de Trabalho Básico de Design de PCB

Create a new KiCAD project named 'LEDBoard' in my Documents folder.
Set the board size to 50mm x 50mm and add a rectangular outline.
Place a mounting hole at each corner, 3mm from the edges, with 3mm diameter.
Add text 'LED Controller v1.0' on the front silkscreen at position x=25mm, y=45mm.

Posicionamento de Componentes

Place an LED at x=10mm, y=10mm using footprint LED_SMD:LED_0805_2012Metric.
Create a grid of 4 resistors (R1-R4) starting at x=20mm, y=20mm with 5mm spacing.
Align all resistors horizontally and distribute them evenly.

Roteamento

Create a net named 'LED1' and route a 0.3mm trace from R1 pad 2 to LED1 anode.
Add a copper pour for GND on the bottom layer covering the entire board.
Create a differential pair for USB_P and USB_N with 0.2mm width and 0.15mm gap.

Autoroteamento com Freerouting

Route automaticamente todas as nets não conectadas usando o autorouter Freerouting.

Configuração (única):

# 1. Download the Freerouting JAR
mkdir -p ~/.kicad-mcp
curl -L -o ~/.kicad-mcp/freerouting.jar \
  https://github.com/freerouting/freerouting/releases/download/v2.0.1/freerouting-2.0.1-executable.jar

# 2. Runtime — pick ONE:
#    Option A: Docker (recommended, no Java install needed)
docker pull eclipse-temurin:21-jre

#    Option B: Install Java 21+ locally
#    (Ubuntu/Debian) sudo apt install openjdk-21-jre

O autorouter detecta automaticamente qual runtime está disponível (Java 21+ direto, ou fallback para Docker/Podman).

Check if Freerouting is ready on my system.
Autoroute the current board using Freerouting with a 5-minute timeout.

Fluxo de trabalho passo a passo:

1. Open the project at ~/Projects/LEDBoard/LEDBoard.kicad_pcb
2. Check Freerouting dependencies are installed
3. Run autoroute with max 10 passes
4. Run DRC to verify the autorouted result
5. Export Gerbers to the fabrication folder

Fluxo de trabalho manual DSN/SES (para usuários avançados ou autorouters externos):

Export the board to Specctra DSN format.
# ... run Freerouting GUI or another autorouter externally ...
Import the routed SES file from ~/Projects/LEDBoard/LEDBoard.ses

Verificação de Design

Set design rules with 0.15mm clearance and 0.2mm minimum track width.
Run a design rule check and show me any violations.
Export Gerber files to the 'fabrication' folder.

Usando Recursos

Os recursos fornecem acesso somente leitura ao estado do projeto:

Show me the current component list.
What are the current design rules?
Display the board preview.
List all electrical nets.

Seleção de Componentes JLCPCB

Encontrando Componentes com Bibliotecas Locais:

Search for ESP32 modules in JLCPCB libraries.
Find a 10k resistor in 0603 package from installed libraries.
Show me details for LCSC part C2934196.

Otimizando Custos com a API JLCPCB:

Search for 10k ohm resistors in 0603 package, only Basic parts.
Find the cheapest capacitor 10uF 25V in 0805 package with good stock.
Show me pricing and stock for JLCPCB part C25804.
Suggest cheaper alternatives to C25804.

Fluxo de Trabalho Completo de Design:

I'm designing a board with an ESP32 and need to select components for JLCPCB assembly.
Search JLCPCB for ESP32-C3 modules.
Find Basic parts for: 10k resistor 0603, 100nF capacitor 0603, LED 0805.
For each component, show me the cheapest option with good stock availability.
Place these components on my board using the suggested footprints.

Gerenciamento do Banco de Dados:

Download the JLCPCB parts database (first time setup).
Show me JLCPCB database statistics.
How many Basic parts are available?

Arquitetura

Camada de Protocolo MCP

Transporte JSON-RPC 2.0: Comunicação bidirecional via STDIO
Versão do Protocolo: MCP 2025-06-18
Capacidades: Ferramentas (122), Recursos (8)
Roteador de Ferramentas: Sistema inteligente de descoberta com 13 categorias
Tratamento de Erros: Códigos de erro JSON-RPC padrão

Servidor TypeScript (`src/`)

Implementa a especificação do protocolo MCP
Gerencia o ciclo de vida do subprocesso Python
Trata roteamento e validação de mensagens
Fornece registro de logs e recuperação de erros
Catálogo de descoberta:
- src/tools/registry.ts — Categorização e consulta de ferramentas
- src/tools/router.ts — list_tool_categories, get_category_tools, search_tools
- Somente pesquisa e navegação. Não bloqueia quais ferramentas chegam ao cliente, portanto não economiza contexto; a execução indireta foi removida em 963a39c porque causava alucinação de schema. Veja ROUTER_ARCHITECTURE.md.

Interface Python (`python/`)

kicad_interface.py: Ponto de entrada principal, manipulador de mensagens MCP, roteamento de comandos
kicad_api/: Implementações de backend
- base.py — Classes base abstratas para backends
- ipc_backend.py — Backend da API IPC do KiCAD 9.0 (sincronização de UI em tempo real)
- swig_backend.py — Backend da API SWIG do pcbnew (operações baseadas em arquivo)
- factory.py — Detecção automática e instanciação de backend
schemas/tool_schemas.py: Definições de esquema JSON para todas as ferramentas
resources/resource_definitions.py: Manipuladores de recursos e URIs
commands/: Implementações modulares de comandos
- project.py — Operações de projeto
- board.py — Manipulação de placa
- component.py — Posicionamento de componentes
- routing.py — Roteamento de trilhas e nets
- design_rules.py — Operações de DRC
- export.py — Geração de arquivos
- schematic.py — Design de esquemático
- library.py — Bibliotecas de footprints
- library_symbol.py — Pesquisa de bibliotecas de símbolos (bibliotecas JLCPCB locais)
- jlcpcb.py — Cliente da API JLCPCB
- jlcpcb_parts.py — Gerenciador do banco de dados de componentes JLCPCB

Integração KiCAD

API pcbnew (SWIG): Bindings Python diretos para o KiCAD para operações de arquivo
API IPC (kipy): Comunicação em tempo real com a instância do KiCAD em execução (experimental)
Backend Híbrido: Usa IPC automaticamente quando disponível, com fallback para SWIG
kicad-skip: Manipulação de arquivos de esquemático
Detecção de Plataforma: Tratamento de caminhos multiplataforma
Gerenciamento de UI: Inicialização/detecção automática da UI do KiCAD

Desenvolvimento

Compilando a partir do Código-Fonte

# Install dependencies
npm install
pip3 install -r requirements.txt

# Build TypeScript
npm run build

# Watch mode for development
npm run dev

Executando Testes

# TypeScript tests
npm run test:ts

# Python tests
npm run test:py

# All tests with coverage
npm run test:coverage

Lint e Formatação

# Lint TypeScript and Python
npm run lint

# Format code
npm run format

Solução de Problemas

Servidor Não Aparecendo no Cliente

Sintomas: O servidor MCP não aparece no Claude Desktop ou no Cline

Soluções:

Verifique se a compilação foi concluída: ls dist/index.js
Verifique se os caminhos na configuração são absolutos
Reinicie o cliente MCP completamente
Verifique os logs do cliente em busca de mensagens de erro

Erros de Importação de Módulos Python

Sintomas: ModuleNotFoundError: No module named 'pcbnew'

Soluções:

Verifique a instalação do KiCAD: python3 -c "import pcbnew"
Verifique se o PYTHONPATH na configuração corresponde à sua instalação do KiCAD
Certifique-se de que o KiCAD foi instalado com suporte a Python

Falhas na Execução de Ferramentas

Sintomas: As ferramentas falham com erros pouco claros

Soluções:

Verifique os logs do servidor: ~/.kicad-mcp/logs/kicad_interface.log
Verifique se um projeto está carregado antes de executar operações de placa
Certifique-se de que os caminhos de arquivo sejam absolutos, não relativos
Verifique se os tipos de parâmetros das ferramentas correspondem aos requisitos do esquema

Problemas Específicos do Windows

Sintomas: O servidor falha ao iniciar no Windows

Soluções:

Execute o diagnóstico automatizado: .\setup-windows.ps1
Verifique se o caminho do Python usa barras invertidas duplas: C:\\Program Files\\KiCad\\10.0
Verifique o Visualizador de Eventos do Windows para erros do Node.js
Veja o Guia de Solução de Problemas do Windows

Obtendo Ajuda

Verifique as Issues do GitHub
Revise os logs do servidor: ~/.kicad-mcp/logs/kicad_interface.log
Abra uma nova issue com:
- Sistema operacional e versão
- Versão do KiCAD (python3 -c "import pcbnew; print(pcbnew.GetBuildVersion())")
- Versão do Node.js (node --version)
- Mensagem de erro completa e stack trace
- Trechos relevantes dos logs

Status do Projeto

Versão Atual: 2.5.0

Veja STATUS_SUMMARY.md para a matriz de status completa e CHANGELOG.md para notas detalhadas de versão.

Recursos em Funcionamento (146 ferramentas):

Gerenciamento de projetos com checkpointing de snapshots
Design completo de placas (contorno, camadas, zonas, furos de montagem, texto, logotipos SVG)
Posicionamento de componentes com matrizes, alinhamento e duplicação
Roteamento avançado (pad-a-pad com via automática, pares diferenciais, cópia de padrões)
Fluxo de trabalho completo de esquemáticos com carregamento dinâmico de símbolos (~10.000 símbolos)
Sistema de fiação inteligente com descoberta de pinos e roteamento inteligente
Fluxo de trabalho de passagem FFC/cabo fita
Sincronização esquemático-para-placa
Verificação de regras de design (DRC e ERC)
Exportação para Gerber, PDF, SVG, 3D, BOM, netlist, arquivo de posição
Criação de footprints e símbolos personalizados
Integração de componentes JLCPCB (catálogo com mais de 2,5 milhões de componentes)
Enriquecimento de datasheets via LCSC
Integração com autorouter Freerouting (Java, Docker, Podman)
Inicialização automática e gerenciamento de UI
Conformidade total com o protocolo MCP 2025-06-18

Backend IPC (Experimental):

Sincronização de UI em tempo real via API IPC do KiCAD
21 comandos habilitados para IPC com fallback automático para SWIG
Carregamento híbrido de footprints (SWIG para acesso à biblioteca, IPC para posicionamento)

Modo Desenvolvedor: Defina KICAD_MCP_DEV=1 para capturar logs de sessão MCP para depuração. Consulte o CHANGELOG v2.2.3 para detalhes.

Logs (~/.kicad-mcp/logs/): Os logs usam INFO como padrão e o arquivo tem limite de tamanho para não crescer sem controle. Ajuste via ambiente do servidor MCP:

Variável	Padrão	Propósito
`LOG_LEVEL` / `KICAD_MCP_LOG_LEVEL`	`info`	Nível de verbosidade do log (`error`/`warn`/`info`/`debug`, ou `off`). `KICAD_MCP_LOG_LEVEL` vence.
`KICAD_MCP_LOG_MAX_BYTES`	`10485760` (10 MB)	Tamanho máximo por arquivo de log antes de rotacionar; `0` desativa a rotação.
`KICAD_MCP_LOG_BACKUP_COUNT`	`3`	Número de backups rotacionados a manter.
`KICAD_MCP_DEBUG_SKIP`	não definido	Defina como `1` para reativar os logs DEBUG detalhados do kicad-skip (silenciados por padrão).

Veja ROADMAP.md para recursos planejados.

O que você quer ver a seguir?

Estamos desenvolvendo ativamente novos recursos. Seu feedback molda diretamente as prioridades de desenvolvimento.

Compartilhe suas ideias:

Abra uma solicitação de recurso
Participe da discussão
Dê uma estrela no repositório se você achar útil

Contribuindo

Contribuições são bem-vindas! Por favor, siga estas diretrizes:

Relatar Bugs: Abra uma issue com etapas de reprodução
Sugerir Recursos: Descreva o caso de uso e o comportamento esperado
Enviar Pull Requests:
- Faça um fork do repositório
- Crie um branch de recurso
- Siga o estilo de código existente
- Adicione testes para novas funcionalidades
- Atualize a documentação
- Envie o PR com uma descrição clara

Veja CONTRIBUTING.md para diretrizes detalhadas.

Licença

Este projeto é licenciado sob a Licença MIT. Veja LICENSE para detalhes.

Agradecimentos

Construído sobre o Model Context Protocol da Anthropic
Alimentado pelo KiCAD, software de design de PCB de código aberto
Usa kicad-skip para manipulação de esquemáticos
JLCSearch API por @tscircuit - API pública de peças JLCPCB
JLCParts Database por @yaqwsx - Dados de peças JLCPCB

Contribuidores da Comunidade

@Kletternaut - Ferramentas de roteamento/componentes, criadores de footprint/símbolo, fluxo de trabalho passthrough, correções de template (PRs #44, #48, #49, #51, #53, #57, #59)
@Mehanik - Ferramentas de inspeção/edição de esquemáticos, posições de campos de componentes (PRs #60, #66, #67)
@jflaflamme - Integração do autorouter Freerouting com suporte a Docker/Podman (PR #68)
@l3wi - Busca local de biblioteca de símbolos, suporte a bibliotecas de terceiros JLCPCB (PR #25)
@gwall-ceres - Conformidade com o protocolo MCP, compatibilidade com Windows (PR #10)
@fariouche - Correções de bugs (PR #17)
@shuofengzhang - Tratamento de caminhos relativos XDG (PR #58)
@sid115 - Melhorias no script de configuração do Windows (PR #13)
@pasrom - Correções de bugs do servidor MCP (PR #50)

Citação

Se você usar este projeto em sua pesquisa ou publicação, por favor cite:

@software{kicad_mcp_server,
  title = {KiCAD MCP Server: AI-Assisted PCB Design},
  author = {mixelpixx},
  year = {2025},
  url = {https://github.com/mixelpixx/KiCAD-MCP-Server},
  version = {2.3.0}
}

KiCAD-MCP-Server

Documentação

Discussões. Entre aqui.

🚀 Conheça o Konnect — a próxima geração

Servidor MCP KiCAD

Visão geral

Experimente o Arduino MCP — agora você pode pedir ajuda ao Claude na IDE, em tempo real!:

O que há de novo na v2.6.0

Um bug que derrubava a sessão foi corrigido

10 novas ferramentas

Suas classes de rede .kicad_pro não desaparecem mais

Quebra: ferramentas de esquemático falham ruidosamente em uma folha não analisável

O que há de novo na v2.5.0

20 novas ferramentas de ciclo de vida e geometria de placa

Formatação normalizada e aplicada

O que há de novo na v2.4.1

Três ferramentas que eram registradas mas não tinham backend agora funcionam

Falhas silenciosas removidas

Novas ferramentas de fornecimento de peças

CI agora realmente executa a suíte de testes

O que há de novo na v2.4.0

Gerenciamento de bibliotecas de símbolos

Descoberta de símbolos mais rápida

Correções que restauram a operação básica

O que há de novo na v2.3.1

Importação de esquemáticos Eagle

Ferramentas de modelos 3D e recarga interativa

Cluster de scaffolding completo

Compatibilidade com KiCad 10

O que há de novo na v2.3.0

Corrupção de esquemáticos no KiCad 10 — ambos os mecanismos corrigidos

Suas edições estão protegidas

Funciona em uma instalação Windows padrão

Novas ferramentas de layout

Novidades na v2.2.3

Novas Ferramentas: Fluxo de Trabalho de Passagem de Cabo FFC/Fita

Correções de Bugs (KiCAD 9 / Windows)

Modo Desenvolvedor

Novidades na v2.1.0

Correção Crítica no Fluxo de Trabalho Esquemático + Sistema de Fiação Completo (Issue #26)

Backend IPC (Experimental)

Padrão de Descoberta de Ferramentas e Roteador

PRECISA DE TESTES - RELATE PROBLEMAS

Integração de Peças JLCPCB (Novo!)

Esquemas Abrangentes de Ferramentas

Capacidade de Recursos

Conformidade com Protocolo

Ferramentas Disponíveis

Gerenciamento de Projeto (5 ferramentas)

Operações de Placa (12 ferramentas)

Gerenciamento de Componentes (16 ferramentas)

Roteamento (13 ferramentas)

Esquemático (27 ferramentas)

Regras de Design / DRC (8 ferramentas)

Exportação (8 ferramentas)

Bibliotecas de Footprint (4 ferramentas) e Bibliotecas de Símbolos (4 ferramentas)

Criador de Footprint (4 ferramentas) e Criador de Símbolos (4 ferramentas)

Ferramentas de Datasheet (2 ferramentas)

Integração JLCPCB (5 ferramentas)

Autorouter Freerouting (4 ferramentas)

Gerenciamento de UI (2 ferramentas)

Pré-requisitos

Software Necessário

Plataformas Suportadas

Instalação

Linux (Ubuntu/Debian)

Windows 10/11

macOS

Configuração Manual

Configuração Automatizada

Uso Básico

Verificar configuração (sem alterações)

Visualizar configuração (teste seco)

Aplicar configuração

Parâmetros

Parâmetros obrigatórios

Parâmetros opcionais

--name NAME

--claude-config PATH

--yes

Suas classes de rede `.kicad_pro` não desaparecem mais

`--name NAME`

`--claude-config PATH`

`--yes`

Servidor TypeScript (`src/`)

Interface Python (`python/`)