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
2.5k
Experimente este MCPPatrocinado

Documentação

Discussões. Venha participar.

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 de SWIG, com 171 ferramentas, habilidades 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 na 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 das operações de design de PCB.

Principais Capacidades:

  • 244 ferramentas registradas, 184 delas indexadas para descoberta por palavras-chave
  • 184 ferramentas em 17 categorias com validação JSON Schema
  • Descoberta de ferramentas por palavras-chave via search_tools / get_category_tools
  • 23 recursos dinâmicos expondo o estado do projeto
  • Fluxo de trabalho completo de esquemáticos com 65 ferramentas (autoria, edições em lote, hierarquia, layout) e carregamento dinâmico de símbolos (~10.000 símbolos)
  • Integração com o autorouter Freerouting (Java, Docker ou Podman)
  • Ferramentas personalizadas de criação de footprints e símbolos
  • Integração de peças JLCPCB com catálogo de 2,5M+ 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 interface do KiCAD via API IPC (experimental)
  • Tratamento abrangente de erros e registro de logs

Experimente o Arduino MCP - agora você pode contar com a ajuda do Claude no IDE, em tempo real!:

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

Novidades na v2.8.2

Uma versão de correção com três correções. As bibliotecas padrão do KiCad 10 são encontradas em instalações onde a tabela de bibliotecas global se refere a elas por meio de uma variável. Novas folhas são escritas da maneira que o KiCad as escreve. Uma quebra de linha em um valor não faz mais o KiCad descartar uma folha. Agradecimentos a @zerthimon, que relatou e corrigiu os dois primeiros e rastreou o terceiro.

Bibliotecas padrão do KiCad 10

  • As tabelas de bibliotecas globais do KiCad 10 contêm uma linha que aponta para a própria tabela de bibliotecas padrão do KiCad. Quando essa linha usa ${KICAD10_TEMPLATE_DIR}, como no Linux, o servidor não encontrava nenhuma delas: search_symbols retornava vazio e list_library_symbols falhava para Device. A linha agora é seguida, então todas as 223 bibliotecas de símbolos e 155 bibliotecas de footprints são encontradas (#438, #439).
  • Carregar uma tabela de bibliotecas passou de cerca de meio segundo para alguns milissegundos, porque as variáveis de caminho agora são resolvidas uma vez por tabela em vez de uma vez por linha.

Folhas hierárquicas

  • add_hierarchical_sheet escreve uma folha da maneira que o KiCad faz. Ele usa os nomes de propriedade Sheetname e Sheetfile, e coloca o número da página dentro do bloco da folha, uma vez para cada uso da folha pai. O KiCad 10 sinalizou o formato antigo quando o projeto foi aberto (#436, #437).
  • Os números de página são únicos em todo o projeto, e adicionar uma folha dentro de uma sub-folha não falha mais.

Quebras de linha em valores

  • Um valor de várias linhas, como uma Descrição definida com edit_schematic_component, era escrito com uma quebra de linha bruta que o KiCad não consegue ler. Em uma sub-folha, o KiCad então deixava a folha inteira fora do design sem um erro. Na demonstração complex_hierarchy do KiCad, um desses valores reduziu a netlist de 68 componentes para 10. As quebras de linha agora são escritas da maneira que o KiCad as escreve (#441).
  • get_schematic_component retorna campos cujos valores contêm aspas, como a Descrição do símbolo GND padrão do KiCad. Antes, esses campos estavam ausentes do seu resultado.

Instalação

  • As instruções de instalação agora clonam o branch stable, que contém o lançamento mais recente. main pode conter correções que ainda não foram lançadas.

Detalhes completos no CHANGELOG.

Novidades na v2.8.1

Uma versão de correção com três correções para esquemáticos hierárquicos e máquinas somente com KiCad 10. Elas surgiram da revisão das correções que entraram na v2.8.0.

Peças em folhas reutilizadas recebem uma referência por uso

  • Uma folha colocada mais de uma vez recebe uma entrada de instância, com sua própria referência, para cada uso. A demonstração complex_hierarchy do KiCad usa uma folha de amplificador duas vezes. Antes, uma peça colocada lá tinha uma entrada, e o kicad-cli a listava duas vezes com "schematic has annotation errors" (#428).
  • annotate_schematic numera cada uso separadamente e pula números já usados em outras folhas do projeto. Ele mantém as unidades de uma peça de múltiplas unidades em um número e dá aos símbolos de alimentação o zero à esquerda do KiCad (#432).
  • add_schematic_component, batch_add_components e annotate_schematic relatam a referência em cada uso, para que os chamadores não deem esses números a outras peças.
  • Folhas mantidas em um subdiretório agora encontram sua raiz, como na demonstração royalblue54L_feather do KiCad, que mantém suas folhas em sch/. add_hierarchical_sheet escreve caminhos corretos em qualquer profundidade (#428).

Máquinas somente com KiCad 10

  • O registro de bibliotecas globais escreve a tabela da versão mais recente do KiCad. Ele costumava criar uma tabela 9.0 que o KiCad 10 nunca lê. Sem tabela global ainda, agora retorna um erro, porque criar uma esconderia as bibliotecas padrão do KiCad (#425).
  • ${KICAD10_3RD_PARTY} (bibliotecas do Plugin and Content Manager) resolve em seu local padrão. A DLL cairo agora é encontrada em instalações do KiCad 10 e pastas de instalação personalizadas (#425).

Detalhes completos no CHANGELOG.

Novidades na v2.8.0

Um worker travado ou preso se recupera sozinho

Uma única solicitação ruim podia encerrar o worker Python, e um comando que travava dentro do pcbnew bloqueava todas as chamadas enfileiradas atrás dele. De qualquer forma, toda chamada de ferramenta posterior falhava até que o servidor MCP fosse reiniciado manualmente. Agora, uma solicitação cuja resposta não pode ser enviada recebe um erro em vez de encerrar o worker (#405), e a ponte reinicia um worker que sai ou trava, falhando apenas a chamada em andamento (#390, @siddolo). Um worker que continua travando permanece desligado após três reinicializações em cinco minutos em vez de renascer para sempre. No Windows, um arquivo de log bloqueado por outro programa não silencia mais o registro de logs, e um kicad-skip ausente agora desativa apenas as ferramentas de esquemático que precisam dele (#389, @AmirF194).

Edições de esquemático chegam onde o KiCad espera

  • Peças colocadas em uma sub-folha recebem o caminho de instância hierárquico que o KiCad escreve (#423, @zerthimon).
  • connect_to_net não coloca mais um rótulo onde o pino de uma peça movida costumava estar (#427).
  • add_schematic_wire relata um endpoint que não se encaixou em um pino em vez de chamar um fio flutuante de sucesso (#404, relatado por @andersresen).
  • Uma unidade de uma peça de múltiplas unidades pode ser movida, girada ou excluída sozinha, arrastar mantém a fiação ortogonal e carrega sinalizadores de não-conexão, os rótulos de rede enfrentam a direção do pino, e os símbolos colocados mantêm a visibilidade de campo da biblioteca (#391, @komar3456).
  • edit_component realmente troca o footprint, mantendo redes, o link de esquemático, atributos e o bloqueio (#411, @AmirF194).
  • sync_schematic_to_board lê apenas as folhas do próprio design e mantém redes sem rótulo (#400, #402), e colocar um símbolo não escreve mais atributos somente do KiCad 10 em esquemáticos do KiCad 8 ou 9 (#351).

Driver de GUI, opt-in

Onze ferramentas controlam a GUI ao vivo do KiCad: menus, barras de ferramentas, diálogos e botões de plugins de ação (#333, @rossvonfange). Nada é instalado até você executar install_gui_driver, e o auxiliar escuta apenas quando KICAD_GUI_DRIVER_ENABLE=1 está definido, em 127.0.0.1, com um token por sessão.

KiCad 10, IPC e Freerouting

  • A colocação IPC no KiCad 10 coloca o footprint real da biblioteca novamente (#378, @AlloyPlane), e a rotação IPC mantém modelos 3D (#422, @Putpluto).
  • KiCad 10 e pastas de instalação personalizadas são encontradas no Windows (#416, @DieterMayerOSS; scripts de configuração: #356, @LiJoeAllen), e um KiCad iniciado a partir de PATH é detectado no Linux (#401, @famez).
  • O diálogo de asserção PCB_VIA::GetWidth no KiCad 9 e 10 desapareceu, e o KiCad 8 funciona novamente (#398, @scorp508).
  • autoroute e import_ses relatam uma importação falha em vez de sucesso, a versão Java é lida do JAR do Freerouting, e trilhas roteadas mantêm o afastamento de borda ao redor de furos de montagem (#417, #418, #419, @outstanda).

Listagem de redes mais rápida

list_schematic_nets e generate_netlist resolvem cada rede em uma passagem por folha: cerca de dez vezes mais rápido nos projetos de demonstração do KiCad, com resultados idênticos (#394, @markszente).

Novas ferramentas

  • Driver de GUI: as onze ferramentas acima.
  • Digi-Key: digikey_search_parts, digikey_check_library_availability, digikey_test_connection (#368, @karu2003).
  • set_net_color (#375, @JMcordobamendez).

search_tools agora indexa 184 das 244 ferramentas registradas, em 17 categorias.

Detalhes completos no CHANGELOG.

Novidades na v2.7.0

A ponte não cruza mais seus fios

O protocolo Node-Python não tinha IDs de solicitação: após um timeout, o próximo comando era silenciosamente resolvido com o resultado atrasado do comando anterior, e toda resposta depois disso estava defasada. As chamadas de ferramenta agora carregam um ID que o Python ecoa de volta; respostas obsoletas são descartadas em vez de serem entregues erroneamente (#373). O transporte MCP também conecta antes do Python ser iniciado, então os clientes não se acumulam mais contra um servidor silencioso por até dois minutos durante o aquecimento do pcbnew (#377).

Duas classes de corrupção de arquivo corrigidas

add_symbol_property descartava um parêntese de fechamento em toda chamada e podia emendar um símbolo de unidade em um irmão de nível superior (#362, @karu2003). E o escape S-expression agora é simétrico: leituras (#336) e escritas (#324) compartilham uma implementação ciente de escape, então um valor de propriedade contendo \" sobrevive a uma ida e volta — 419 dos arquivos de símbolos padrão do próprio KiCad carregam tais valores.

8 novas ferramentas

  • Validação: validate_schematic, validate_symbol_library — localizam danos estruturais com linha/coluna, confirmados via kicad-cli em uma cópia.
  • Tabelas de bibliotecas: list_library_table, remove_library_table_entry, set_library_table_uri — o CRUD ausente em torno de register_*_library.
  • Edição de símbolos: set_symbol_pin_type (correções em massa de tipo de pino com simulação), find_duplicate_symbols (a mesma peça armazenada duas vezes).
  • Back-annotation: backannotate_footprints — as escolhas de footprint da PCB fluem de volta para o esquemático, o inverso de sync_schematic_to_board.

Tudo por @karu2003. Com #359 (@AmirF194) registrando 15 ferramentas de símbolos existentes, search_tools agora indexa 169 ferramentas em 15 categorias.

Qualidade de vida

  • autoroute prepara seus arquivos de trabalho .dsn/.ses em um diretório temporário e limpa em toda saída — sem mais lixo ao lado da sua placa, sem importações SES obsoletas, e uma execução interrompida diz "terminated externally" em vez de exit code 4294967295 (#249, escopado pelos rastreamentos de @Dewieinns).
  • Símbolos colocados herdam o Footprint padrão da biblioteca (#300, implementação por @stefangordon).
  • add_layer realmente adiciona camadas internas de cobre (#222) — anteriormente escrevia em IDs de camadas não-cobre e renomeava F.SilkS.
  • sync_schematic_to_board corresponde por UUID de símbolo, não apenas refdes (#250).
  • As ferramentas JLCPCB decodificam o novo esquema upstream source-db-v2 (#352, @stefanobaldo) e degradam graciosamente quando o banco de dados de peças está indisponível (#264, @fage2022).
  • setup-macos.sh --verify agora falha quando os requisitos Python estão ausentes em vez de passar em um servidor que não pode iniciar (#350, @francisrath).

Detalhes completos no CHANGELOG.

Novidades na v2.6.0

Um bug que matava a sessão foi corrigido

Deletar qualquer coisa de uma placa — um componente, um traço, um contorno de placa — funcionou exatamente uma vez. A próxima operação, mesmo uma simples leitura, falhava com um erro SwigPyObject, e apenas close_project e depois open_project recuperavam. BOARD.Remove() entrega a propriedade do C++ ao Python, então descartar a referência executava um destrutor em um objeto que 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 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 quebra silenciosamente 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 param de desaparecer

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 netclass_patterns. Abrir um projeto não reescreve mais o arquivo.

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 estruturado schematic_load_failed nomeando os símbolos problemáticos. Pular silenciosamente uma folha quebrada produzia um mapa pad-para-rede incompleto 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 de placa e geometria

  • 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 complicado 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 portão real de CI, que é o que o CONTRIBUTING sempre afirmou.
  • npm run lint costumava executar black em modo write contra o que black estava em PATH, reformatando silenciosamente sua árvore de trabalho com uma versão que discordava da CI. Agora 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 registradas mas sem 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 manipulador 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 captam — não há API pcbnew para elas.

Falhas silenciosas removidas

  • autoroute foi abandonado pela ponte Node em 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 — 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 lista de hosts, verificados por extensão e limitados por tamanho.
  • get_jlcpcb_part retorna estoque ao vivo e preços em camadas quando as credenciais da Plataforma Aberta 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 de quatro maneiras 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 (Fabricante, 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 todos os projetos sob um diretório — o equivalente programático de 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 bibliotecas, 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 desatualização revalidam caminhos e rastreiam mtime_ns de origem, e os caminhos de escrita mutáveis limpam os caches explicitamente.

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

  • Toda escrita de .kicad_sym e 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 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 ajusta-se à grade de 1,27 mm, import_ses não cria mais redes fantasmas 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ático Eagle

  • import_eagle_schematic converte designs XML .sch Eagle para o formato KiCad com mapeamento de símbolos, fios de rede, peças multi-gate, poda de fios pendentes e relatório ERC de verdade 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_* vaza para arquivos de usuário).
  • Arquivos .kicad_pro correspondem ao que o próprio KiCad escreve.
  • Versão de formato 20260101 garante que todas as builds KiCad 10.0.x 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 fantasmas de pinos entre unidades em get_wire_connections são eliminados.

Detalhes completos no CHANGELOG.

O que há de novo na v2.3.0

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

  • Blocos de instância completos: componentes colocados agora carregam o nome real do projeto, caminho uuid da folha raiz, entradas uuid por pino (ERC pode vincular fios a pinos) e o conjunto completo de campos KiCad 10 — verificado como byte-equivalente ao que o próprio eeschema escreve. Anteriormente, arrastar ou editar um símbolo colocado podia travar o KiCad.
  • Escritas canônicas multilinha: 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 são protegidas

  • Pinning de sessão de backend: um projeto carregado permanece em um backend (SWIG ou IPC) por todo seu ciclo de vida — salvamentos não podem mais rotear silenciosamente para uma placa GUI desatualizada e perder suas edições.
  • Guarda de edição externa: save_project recusa sobrescrever um arquivo de placa cujo conteúdo mudou no disco desde o carregamento (passe force: true para sobrescrever).
  • close_project (nova ferramenta): libere o projeto para que 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 realmente 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 de correções de compatibilidade com KiCad 10 (renomeações de folha, bibliotecas .kicad_symdir fragmentadas, tamanho de placa IPC Box2), geometria correta de pinos para símbolos rotacionados+espelhados e multi-unidade, connects IPC limitados com fallback SWIG e uma suíte Vitest real para a camada TypeScript. Detalhes completos no CHANGELOG.

O que há de novo na v2.2.3

Novas ferramentas: Fluxo de trabalho de passagem FFC/Cabo Fita

Um fluxo de trabalho completo para projetar placas adaptadoras de passagem (ex.: adaptadores de cabo CSI Raspberry Pi) agora é suportado:

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

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

  • Inserção de via para footprints B.Cu — route_pad_to_pad agora detecta corretamente quando um footprint está em B.Cu e insere a via necessária. (SWIG KiCAD 9 retornava F.Cu para todas as pads SMD independentemente da camada — corrigido.)
  • Cantos arredondados de contorno de placa — add_board_outline agora aplica corretamente cornerRadius quando shape="rounded_rectangle".
  • Travamento de colocação 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 seu Claude Desktop para salvar automaticamente o log da sessão MCP na pasta logs/ do projeto em toda chamada export_gerber e snapshot_project. Útil para depuração e para anexar a issues do GitHub.

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

Aviso de privacidade: O log da sessão contém seu histórico completo 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 CHANGELOG para a lista completa de mudanças nesta versão.

O que há de novo na v2.1.0

Correção crítica do fluxo de trabalho de esquemático + sistema de fiação completo (Issue #26)

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

O que estava quebrado:

  • create_project apenas criava arquivos de 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)
  • Sem funcionalidade funcional de fios/conexões

Implementação Completa (3 Fases):

Fase 1: Fundação de Posicionamento de Componentes

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

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
  • Zero configuração necessária — basta especificar o nome da biblioteca e 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 Inteligente de Fiação (NOVO na v2.1.0)

  • Descoberta automática de posiçã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 redes
  • 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:

  1. Modelos Estáticos: 13 símbolos pré-configurados (R, C, L, LED, etc.) para uso imediato
  2. 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 uma 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
  3. Criação de Fios: Injeção de fios baseada em expressões S (contornando as limitações da API kicad-skip)
  4. Descoberta de Pinos: Analisar definições de símbolos, aplicar transformações de rotação, calcular posições absolutas
  5. 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% aprovado
  • Carregamento dinâmico de símbolos: mais de 10.000 símbolos acessíveis
  • Criação de fios: 100% aprovado (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

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

Backend IPC (Experimental)

Estamos atualmente 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 tiver recorrido ao SWIG, as ferramentas de placa compatíveis com 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 zonas

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

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

Descoberta de Ferramentas

Cada ferramenta é registrada individualmente, portanto um cliente MCP pode chamar qualquer uma delas pelo nome. Além disso, a maioria das ferramentas é indexada para que um assistente possa encontrar uma por palavra-chave em vez de adivinhar:

  • 32 ferramentas essenciais que o search_tools apresenta primeiro, cobrindo as operações que quase toda sessão precisa
  • 184 ferramentas indexadas em 17 categorias (placa, componente, exportação, drc, esquemático, biblioteca, biblioteca_de_símbolos, pinos_de_símbolos, hierarquia_de_esquemático, layout_de_esquemático, lote_de_esquemático, roteamento, autoroteamento, validação, registro_de_peças, digikey, driver_gui)
  • 3 ferramentas de descoberta:
    • list_tool_categories — Navegar por todas as categorias disponíveis
    • get_category_tools — Visualizar ferramentas em uma categoria específica
    • search_tools — Encontrar ferramentas por palavra-chave

As 60 ferramentas registradas restantes ainda não são indexadas. Elas funcionam exatamente da mesma forma quando chamadas pelo nome; simplesmente não aparecem nos resultados de search_tools.

Por que isso importa: o assistente pode localizar a ferramenta certa para sua tarefa por palavra-chave em vez de inventar um nome. Observe que a descoberta não reduz o contexto: cada esquema de ferramenta ainda é enviado ao cliente. Um design anterior ocultava ferramentas atrás de um dispatcher execute_tool para economizar contexto; foi removido porque o modelo então inventava esquemas que nunca tinha visto. Consulte ROUTER_ARCHITECTURE.md para esse histórico.

O uso é perfeito: Basta perguntar naturalmente — "exportar arquivos gerber" ou "adicionar furos de montagem" — e o Claude encontrará e chamará 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:

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

Principais Recursos:

  • Preços em tempo real com faixas de quantidade (1+, 10+, 100+, 1000+)
  • Verificação de disponibilidade de estoque
  • Identificação de 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 exclusivo. Esta 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.

Consulte 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 tipos
  • 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 cada ferramenta diretamente, para que seu assistente possa chamar qualquer uma delas sem uma etapa de descoberta — basta pedir o que você deseja realizar. 184 ferramentas são adicionalmente indexadas em 17 categorias funcionais, para que search_tools e get_category_tools possam encontrar uma por palavra-chave.

As listas abaixo são um tour selecionado das ferramentas mais úteis, não o conjunto completo. Para a referência completa e gerada de todas as 244 ferramentas — incluindo como cada uma é descoberta — consulte Inventário de Ferramentas.

Gerenciamento de Projetos (12 ferramentas)

  • create_project — Inicializar novos projetos KiCAD
  • open_project — Carregar arquivos de projeto existentes
  • open_board / reload_board — Abrir ou reler um .kicad_pcb específico
  • save_project / save_board / save_as — Salvar o estado atual
  • close_project — Salvar (opcionalmente) e descartar o estado em memória
  • is_dirty / discard_or_reload — Verificar e desfazer alterações não salvas
  • get_project_info — Recuperar metadados do projeto
  • snapshot_project — Salvar snapshot de checkpoint nomeado

Operações de Placa (19 ferramentas)

  • set_board_size — Configurar dimensões da 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 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
  • clear_board_outline / replace_board_outline — Remover ou trocar o contorno Edge.Cuts
  • set_board_origin / get_board_origin — Ler e definir as origens de furação/colocação e grade
  • list_graphics / update_graphic / delete_graphic — Inspecionar e editar itens de desenho
  • import_svg_logo — Importar arquivo SVG como polígonos de serigrafia da PCB

Gerenciamento de Componentes (28 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 pads
  • get_component_list — Listar todos os componentes colocados
  • get_pad_position — Obter posição precisa do pad
  • place_component_array — Criar grades/padrões de componentes
  • align_components — Alinhar múltiplos componentes
  • duplicate_component — Copiar componente existente
  • batch_move_components — Mover muitos componentes em uma única chamada transacional
  • get_component_geometry / check_placement_clearance — Tamanhos de corpo e verificações de sobreposição
  • get_ratsnest / estimate_airwire_lengths — Análise de conexões não roteadas

Roteamento (17 ferramentas)

  • add_net — Criar rede 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 rede)
  • query_traces — Consultar/filtrar trilhas
  • get_nets_list — Listar todas as redes com estatísticas
  • modify_trace — Alterar largura da trilha, camada ou rede
  • create_netclass — Definir classe de rede com regras
  • add_copper_pour — Criar zonas/preenchimentos de cobre
  • route_differential_pair — Roteamento de sinais diferenciais
  • refill_zones — Reencher todas as zonas de cobre
  • copy_routing_pattern — Replicar roteamento entre grupos de componentes
  • set_net_color — Definir ou limpar a substituição de cor de exibição de uma rede
  • route_arc_trace — Roteamento de trilha curva
  • add_gnd_stitching_vias — Costurar um plano de terra com vias
  • query_zones — Inspecionar zonas de cobre

Esquemático (46 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 - Posicionar símbolos de qualquer biblioteca do KiCad
  • delete_schematic_component - Remover componente
  • edit_schematic_component - Editar footprint, valor, referência, posições de rótulos 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ótulos
  • list_schematic_components - Listar todos os componentes
  • move_schematic_component - Reposicionar componente
  • rotate_schematic_component - Rotacionar componente
  • annotate_schematic - Atribuir automaticamente designadores de referência

Fiação e Conexões:

  • add_schematic_wire - Criar fio entre pontos
  • delete_schematic_wire - Remover segmento de fio
  • add_no_connect - Marcar um pino como deliberadamente não conectado
  • add_schematic_net_label - Adicionar rótulos de rede (VCC, GND, sinais)
  • delete_schematic_net_label - Remover rótulo de rede
  • connect_to_net - Conectar pino a rede 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 rede
  • 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 redes/pads para PCB (equivalente a F8)
  • backannotate_footprints - Copiar escolhas de footprint da placa de volta para o esquemático
  • create_board_from_schematic - Criar uma placa populada a partir do esquemático

Lote, Hierarquia e Layout (mais 19 ferramentas):

  • batch_add_components / batch_edit_schematic_components / batch_connect - Criação em massa
  • add_hierarchical_sheet / create_hierarchical_subsheet - Projetos com múltiplas folhas
  • autoplace_schematic_fields / lint_schematic_cosmetic - Organizar posicionamento de campos
  • lint_offgrid / snap_to_grid - Encontrar e corrigir coordenadas fora da grade

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

Validação de Arquivos (2 ferramentas)

Encontre danos estruturais antes que o KiCad se recuse a abrir um arquivo. Ambos relatam a linha e a coluna de cada falha, e confirmam o veredito com kicad-cli executado contra uma cópia descartável.

  • validate_schematic - Verificar um arquivo .kicad_sch
  • validate_symbol_library - Verificar um arquivo .kicad_sym

Regras de Design / DRC (7 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 rede
  • set_layer_constraints / check_clearance - Regras de camadas e folgas

Exportação (27 ferramentas)

  • export_gerber / export_gerbers / export_gerber_single - Arquivos de fabricação Gerber
  • export_drill - Arquivos de perfuração
  • export_ipc2581 / export_odb / export_ipcd356 / export_gencad - Outros formatos de fabricação
  • export_pdf / export_svg / export_pcb_dxf - Documentação e gráficos vetoriais
  • export_3d - Modelos 3D (STEP, STL, VRML, OBJ)
  • export_bom / export_sch_bom - Lista de materiais (CSV, XML, HTML, JSON)
  • export_netlist - Netlist (KiCad, Spice, Cadstar, OrcadPCB2)
  • export_position_file / export_pos - Posições de componentes para pick and place
  • export_sch_pdf / export_sch_svg / export_sch_dxf - Saída de esquemático
  • export_vrml - Modelo 3D VRML

Bibliotecas de Footprints e Bibliotecas de Símbolos (16 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
  • list_symbol_pins / batch_list_symbol_pins - Ler pinos diretamente de uma biblioteca
  • set_symbol_pin_type - Definir em massa tipos elétricos de pinos, com uma execução de teste primeiro
  • find_duplicate_symbols - Encontrar a mesma peça armazenada duas vezes com nomes diferentes
  • repair_flat_symbols - Corrigir símbolos de fornecedores que o KiCad tolera, mas ferramentas não conseguem analisar

Tabelas de bibliotecas (sym-lib-table / fp-lib-table):

  • list_library_table - Ler cada biblioteca registrada e verificar se seu URI resolve
  • remove_library_table_entry - Cancelar registro de uma biblioteca
  • set_library_table_uri - Redirecionar uma biblioteca que foi movida

Criador de Footprints (7 ferramentas) e Criador de Símbolos (8 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 pads
  • add_footprint_3d_model / add_component_3d_model / import_3d_model - Anexar modelos 3D
  • register_footprint_library / register_symbol_library - Registrar na tabela de bibliotecas
  • list_footprint_libraries / list_symbols_in_library - Navegar por bibliotecas personalizadas
  • add_symbol_property - Adicionar ou atualizar um campo em um símbolo de biblioteca
  • import_symbol / export_symbol / rename_symbol - Mover símbolos entre bibliotecas
  • delete_symbol - Remover símbolo da biblioteca

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

Ferramentas de Datasheet (2 ferramentas)

  • enrich_datasheets - Preencher automaticamente URLs de datasheets 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 2,5M+ peças (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 do Freerouting para configuração e uso.

Gerenciamento de Interface (3 ferramentas)

  • check_kicad_ui - Verificar se o KiCAD está em execução
  • launch_kicad_ui - Iniciar o aplicativo KiCAD
  • get_backend_state - Relatar qual backend (IPC ou SWIG) está em uso

Registro de Peças (3 ferramentas)

Procure por uma peça pronta antes de gerar uma personalizada.

  • search_parts_registry - Pesquisar o registro por nome, palavra-chave ou fabricante
  • get_registry_part - Inspecionar uma peça em detalhes
  • download_registry_part - Baixar seu footprint, símbolo ou modelo 3D

Importação (2 ferramentas)

  • import_eagle_project - Converter um projeto Eagle
  • import_pcb - Carregar um .kicad_pcb existente na sessão

Pré-requisitos

Software Necessário

KiCAD 9.0 ou superior

  • Baixe em 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 em nodejs.org
  • Verifique: node --version e npm --version

Python 3.9 ou superior

  • Vem incluído com o KiCAD (builds macOS incluem Python 3.9; builds 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

Estas etapas instalam a versão mais recente do branch stable, que só avança quando uma versão é lançada. main também tem correções que ainda não foram lançadas; clone sem --branch stable para usá-lo. Para atualizar uma instalação posteriormente, execute git pull no clone e depois npm install e npm run build novamente.

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 --branch stable 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 --branch stable 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 Plataforma para instruções detalhadas e Solução de Problemas no Windows se a configuração falhar.

macOS

Importante: No macOS, use o Python incluído do 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 --branch stable 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.

Nota: Se você pular o ambiente virtual, instale os requisitos com o interpretador incluído do KiCAD — um pip3 install -r requirements.txt simples vai para o Python do sistema, que o servidor nunca usa, e o servidor então falha ao iniciar (o cliente MCP expira após 30s sem erro visível):

/Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/Current/bin/python3 \
  -m pip install --user -r requirements.txt

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 rodando: chmod +x setup-macos.sh.
  • alternativamente, executá-lo explicitamente com bash: bash setup-macos.sh para que nenhuma alteração de chmod seja necessária.

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 (execução de teste)
./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 isto 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 isto 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 prompt de confirmação ao aplicar alterações.

Exemplo:

./setup-macos.sh --apply --yes
Após a Configuração
  1. Saia completamente do Claude Desktop
  2. Reabra o Claude Desktop
  3. Abra um novo chat
  4. Clique em + → Conectores
  5. Verifique se o servidor aparece (por exemplo, kicad ou seu nome personalizado)

Teste com prompt no Claude Desktop:

Use the kicad MCP server to run check_kicad_ui.
Notas
  • O script apenas modifica a seção mcpServers e deixa toda a outra configuração intacta
  • Configurações existentes são automaticamente copiadas antes das alterações
  • O suporte ao macOS depende do Python incluído do 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:

  1. Ambiente virtual - venv/bin/python ou .venv/bin/python (maior prioridade)
  2. Variável de ambiente KICAD_PYTHON - Substituição pelo usuário para instalações não padronizadas
  3. Python integrado do KiCad - /usr/lib/kicad/bin/python3, /usr/local/lib/kicad/bin/python3, /opt/kicad/bin/python3
  4. Python do sistema via which - Resolve which python3 para o caminho absoluto (ex.: /usr/bin/python3)
  5. 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 de 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 o caminho do seu 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, nenhuma edição de caminho é necessária.

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 não lê o arquivo de configuração do Claude Desktop e só detecta automaticamente servidores listados em um .mcp.json do projeto (este repositório não inclui um). Registre o servidor explicitamente com claude mcp add:

# macOS example — adjust KICAD_PYTHON/PYTHONPATH per platform (see table above)
claude mcp add --scope user kicad \
  --env KICAD_PYTHON=/Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/Current/bin/python3 \
  --env PYTHONPATH=/Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/3.9/lib/python3.9/site-packages \
  --env LOG_LEVEL=info \
  -- node /path/to/KiCAD-MCP-Server/dist/index.js

Com --scope user, o servidor fica disponível em todos os projetos; use --scope project para escrever um .mcp.json compartilhável. No macOS, setup-macos.sh imprime este comando com os caminhos detectados preenchidos.

Verifique com claude mcp list — o servidor deve reportar ✔ Conectado.

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 mcp do OpenCode.

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 é construído
  • 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 OpenCode global disponível em qualquer espaço de trabalho
  • Você precisa verificar o Python do KiCAD (pcbnew), 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 KiCAD via -Backend:

  • auto - tenta IPC primeiro e usa SWIG como fallback se IPC não estiver disponí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 de API IPC habilitado.

Verificar configuração sem alterações

Use isto primeiro ao diagnosticar problemas de instalação ou caminho. Ele detecta o KiCAD, testa pcbnew, verifica o Node.js e valida o ponto de entrada MCP construído.

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

Visualizar configuração do OpenCode

Use o modo de simulação (dry run) quando quiser inspecionar o JSON exato antes de gravá-lo.

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

Exemplo da estrutura OpenCode gerada:

{
  "$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 isto quando quiser que o MCP 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 servidor MCP KiCAD, 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 isto quando quiser que o servidor MCP 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 isto ao testar múltiplos forks ou manter entradas MCP KiCAD de desenvolvimento e estáveis separadas.

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

Usar um caminho de instalação KiCAD personalizado

Use isto 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

  1. Feche completamente o OpenCode.
  2. Inicie o OpenCode novamente para que ele recarregue opencode.json.
  3. 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 de Integração JLCPCB (Opcional)

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

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

A maneira mais fácil de acessar o catálogo de peças da JLCPCB:

  • Nenhuma credencial de API necessária
  • Nenhuma conta JLCPCB necessária
  • Acesso a mais de 2,5 milhões de peças com dados de preço e estoque
  • Tempo de download: 40-60 minutos para o catálogo completo (lotes de 100 peças 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 mais de 2,5 milhões de peças).

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

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

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

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

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

  1. 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
    • Nota: Isso requer histórico de pedidos anterior e aprovação de conta empresarial

  2. 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

Consulte o Guia de Uso 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.

Roteamento Automático com Freerouting

Roteie automaticamente todas as redes não conectadas usando o roteador automático Freerouting.

Configuração (única vez):

# 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 roteador automático detecta automaticamente qual runtime está disponível (Java 21+ direto, ou fallback 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 roteadores 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 de 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 (244), Recursos (23)
  • Descoberta de ferramentas: catálogo de indexação por pesquisa de palavras-chave com 184 ferramentas em 17 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
  • Lida com roteamento e validação de mensagens
  • Fornece registro 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
    • Apenas pesquisa e navegação. Não controla quais ferramentas chegam ao cliente, então não economiza contexto; a execução indireta foi removida em 963a39c porque causava alucinação de esquema. Consulte 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 de comandos modulares
    • project.py - Operações de projeto
    • board.py - Manipulação de placa
    • component.py - Posicionamento de componentes
    • routing.py - Roteamento de trilhas e redes
    • 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 de banco de dados de peças JLCPCB

Integração KiCAD

  • API pcbnew (SWIG): Bindings Python diretos para KiCAD para operações de arquivo
  • API IPC (kipy): Comunicação em tempo real com instância 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 entre plataformas
  • 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 Aparece no Cliente

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

Soluções:

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

Erros de Importação de Módulo Python

Sintomas: ModuleNotFoundError: No module named 'pcbnew'

Soluções:

  1. Verifique a instalação do KiCAD: python3 -c "import pcbnew"
  2. Verifique se o PYTHONPATH na configuração corresponde à sua instalação do KiCAD
  3. Garanta 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:

  1. Verifique os logs do servidor: ~/.kicad-mcp/logs/kicad_interface-<pid>.log (um arquivo por processo de servidor)
  2. Verifique se um projeto está carregado antes de executar operações de placa
  3. Garanta que os caminhos de arquivo sejam absolutos, não relativos
  4. Verifique se os tipos de parâmetros da ferramenta correspondem aos requisitos do esquema

Problemas Específicos do Windows

Sintomas: O servidor falha ao iniciar no Windows

Soluções:

  1. Execute diagnósticos automatizados: .\setup-windows.ps1
  2. Verifique se o caminho do Python usa barras invertidas duplas: C:\\Program Files\\KiCad\\10.0
  3. Verifique o Visualizador de Eventos do Windows para erros do Node.js
  4. Consulte o Guia de Solução de Problemas do Windows

Obtendo Ajuda

  1. Verifique as GitHub Issues
  2. Revise os logs do servidor: ~/.kicad-mcp/logs/kicad_interface-<pid>.log (um arquivo por processo do servidor)
  3. 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.8.2

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

Recursos em Funcionamento (244 ferramentas):

  • Gerenciamento de projetos com checkpointing de snapshots
  • Design completo de placa (contorno, camadas, zonas, furos de montagem, texto, logotipos SVG)
  • Posicionamento de componentes com matrizes, alinhamento e duplicação
  • Roteamento avançado (pad-to-pad com auto-via, 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 de cabos FFC/fita
  • Sincronização esquemático-placa, além de anotação reversa de footprints a partir da placa
  • Verificação de regras de design (DRC e ERC)
  • Validação estrutural de esquemáticos e bibliotecas de símbolos
  • Exportação para Gerber, PDF, SVG, 3D, BOM, netlist, arquivo de posição
  • Criação de footprints e símbolos personalizados
  • Manutenção de tabelas de bibliotecas (listar, remover e redirecionar entradas de símbolos/footprints)
  • Integração de peças JLCPCB (catálogo com 2,5M+ peças)
  • Pesquisa Digi-Key Product Information V4 e varredura de disponibilidade de bibliotecas
  • Driver de GUI opcional: menus, barras de ferramentas, diálogos e botões de plugins da GUI KiCad ativa por meio de um helper localhost protegido por token (install_gui_driver, depois KICAD_GUI_DRIVER_ENABLE=1)
  • Enriquecimento de datasheets via LCSC
  • Integração do autorouter Freerouting (Java, Docker, Podman)
  • Auto-inicialização e gerenciamento da interface
  • Conformidade total com o protocolo MCP 2025-06-18

Backend IPC (Experimental):

  • Sincronização de interface em tempo real via API IPC do KiCAD
  • 21 comandos habilitados por 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 CHANGELOG v2.2.3 para detalhes.

Registro (~/.kicad-mcp/logs/): Os logs são gravados por padrão em INFO e o arquivo tem limite de tamanho para não crescer indefinidamente. Ajuste via ambiente do servidor MCP:

VariávelPadrãoFinalidade
LOG_LEVEL / KICAD_MCP_LOG_LEVELinfoNível de detalhe do log (error/warn/info/debug, ou off). KICAD_MCP_LOG_LEVEL tem prioridade.
KICAD_MCP_LOG_MAX_BYTES10485760 (10 MB)Tamanho máximo por arquivo de log antes da rotação; 0 desativa a rotação.
KICAD_MCP_LOG_BACKUP_COUNT3Número de backups rotacionados a manter.
KICAD_MCP_DEBUG_SKIPnão definidoDefina como 1 para reativar os logs DEBUG detalhados do parser kicad-skip (silenciados por padrão).

Consulte 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:

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

Contribuindo

Contribuições são bem-vindas! Siga estas diretrizes:

  1. Reporte Bugs: Abra uma issue com etapas de reprodução
  2. Sugira Recursos: Descreva o caso de uso e o comportamento esperado
  3. Envie 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

Consulte CONTRIBUTING.md para diretrizes detalhadas.

Licença

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

Agradecimentos

Contribuidores da Comunidade

  • @Kletternaut - Ferramentas de roteamento/componentes, criadores de footprints/símbolos, fluxo de passagem, correções de templates (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 bibliotecas 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 no servidor MCP (PR #50)

Citação

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

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