KiCad MCP Server

Um servidor MCP para KiCad que oferece gerenciamento de projetos, análise de design de PCB, gerenciamento de BOM e verificação de regras de design.

GitHub
524
Experimente este MCPPatrocinado

Documentação

Servidor MCP KiCad

Este guia ajudará você a configurar um servidor Model Context Protocol (MCP) para o KiCad. Embora os exemplos neste guia frequentemente façam referência ao Claude Desktop, o servidor é compatível com qualquer cliente compatível com MCP. Você pode usá-lo com o Claude Desktop, seus próprios clientes MCP personalizados ou qualquer outro aplicativo que implemente o Model Context Protocol.

Índice

Pré-requisitos

  • macOS, Windows ou Linux
  • Python 3.10 ou superior
  • KiCad 9.0 ou superior
  • uv 0.8.0 ou superior
  • Claude Desktop (ou outro cliente MCP)

Etapas de Instalação

1. Configure Seu Ambiente Python

Primeiro, vamos instalar as dependências e configurar nosso ambiente:

# Clone the repository
git clone https://github.com/lamaalrajih/kicad-mcp.git
cd kicad-mcp

# Install dependencies – `uv` will create a `.venv/` folder automatically
# (Install `uv` first: `brew install uv` on macOS or `pipx install uv`)
make install

# Optional: activate the environment for manual commands
source .venv/bin/activate

2. Configure Seu Ambiente

Crie um arquivo .env para personalizar onde o servidor procura seus projetos KiCad:

# Copy the example environment file
cp .env.example .env

# Edit the .env file
vim .env

No arquivo .env, adicione seus diretórios de projeto personalizados:

# Add paths to your KiCad projects (comma-separated)
KICAD_SEARCH_PATHS=~/pcb,~/Electronics,~/Projects/KiCad

3. Execute o Servidor

Uma vez que o ambiente esteja configurado, você pode executar o servidor:

python main.py

4. Configure um Cliente MCP

Agora, vamos configurar o Claude Desktop para usar nosso servidor MCP:

  1. Crie ou edite o arquivo de configuração do Claude Desktop:
# Create the directory if it doesn't exist
mkdir -p ~/Library/Application\ Support/Claude

# Edit the configuration file
vim ~/Library/Application\ Support/Claude/claude_desktop_config.json
  1. Adicione o servidor MCP KiCad à configuração:
{
    "mcpServers": {
        "kicad": {
            "command": "/ABSOLUTE/PATH/TO/YOUR/PROJECT/kicad-mcp/.venv/bin/python",
            "args": [
                "/ABSOLUTE/PATH/TO/YOUR/PROJECT/kicad-mcp/main.py"
            ]
        }
    }
}

Substitua /ABSOLUTE/PATH/TO/YOUR/PROJECT/kicad-mcp pelo caminho real para o seu diretório de projeto.

5. Reinicie Seu Cliente MCP

Feche e reabra seu cliente MCP para carregar a nova configuração.

Entendendo os Componentes do MCP

O Model Context Protocol (MCP) define três formas principais de fornecer capacidades:

Recursos vs Ferramentas vs Prompts

Recursos são fontes de dados somente leitura que os LLMs podem referenciar:

  • Semelhantes aos endpoints GET em APIs REST
  • Fornecem dados sem realizar computação significativa
  • Usados quando o LLM precisa ler informações
  • Tipicamente acessados programaticamente pelo aplicativo cliente
  • Exemplo: kicad://projects retorna uma lista de todos os projetos KiCad

Ferramentas são funções que executam ações ou computações:

  • Semelhantes aos endpoints POST/PUT em APIs REST
  • Podem ter efeitos colaterais (como abrir aplicativos ou gerar arquivos)
  • Usadas quando o LLM precisa executar ações no mundo
  • Tipicamente invocadas diretamente pelo LLM (com aprovação do usuário)
  • Exemplo: open_project() inicia o KiCad com um projeto específico

Prompts são modelos reutilizáveis para interações comuns:

  • Iniciadores de conversa ou instruções pré-definidos
  • Ajudam os usuários a articular perguntas ou tarefas comuns
  • Invocados por escolha do usuário (tipicamente a partir de um menu)
  • Exemplo: O prompt debug_pcb_issues ajuda os usuários a solucionar problemas de PCB

Para mais informações sobre recursos vs ferramentas vs prompts, leia a documentação do MCP.

Destaques de Recursos

O Servidor MCP KiCad fornece vários recursos principais, cada um com documentação detalhada:

  • Gerenciamento de Projetos: Liste, examine e abra projetos KiCad

    • Exemplo: "Mostre-me todos os meus projetos KiCad recentes" → Lista todos os projetos ordenados por data de modificação

  • Análise de Design de PCB: Obtenha insights sobre seus designs de PCB e esquemáticos

    • Exemplo: "Analise a densidade de componentes da minha placa de sensor de temperatura" → Fornece análise de espaçamento de componentes

  • Extração de Netlist: Extraia e analise conexões de componentes de esquemáticos

    • Exemplo: "Quais componentes estão conectados ao MCU no meu shield Arduino?" → Mostra todas as conexões com o microcontrolador

  • Gerenciamento de BOM: Analise e exporte Listas de Materiais

    • Exemplo: "Gere uma BOM para meu projeto de smart watch" → Cria uma lista de materiais detalhada

    • Verificação de Regras de Design: Execute verificações de DRC usando o CLI do KiCad e acompanhe seu progresso ao longo do tempo

    • Exemplo: "Execute DRC na minha placa de fonte de alimentação e compare com a semana passada" → Mostra o progresso na correção de violações

  • Visualização de PCB: Gere representações visuais dos seus layouts de PCB

    • Exemplo: "Mostre-me uma miniatura do meu PCB de amplificador de áudio" → Exibe uma renderização visual da placa

  • Reconhecimento de Padrões de Circuito: Identifique automaticamente padrões de circuito comuns em seus esquemáticos

    • Exemplo: "Quais topologias de fonte de alimentação estou usando no meu dispositivo IoT?" → Identifica reguladores buck, boost ou lineares

Para mais exemplos e detalhes sobre cada recurso, consulte os guias dedicados na documentação. Você também pode perguntar ao LLM quais ferramentas ele tem acesso!

Interação em Linguagem Natural

Embora nossa documentação frequentemente mostre exemplos como:

Show me the DRC report for /Users/username/Documents/KiCad/my_project/my_project.kicad_pro

Você não precisa digitar o caminho completo para seus arquivos! O LLM pode entender solicitações em linguagem mais natural.

Por exemplo, em vez do comando formal acima, você pode simplesmente perguntar:

Can you check if there are any design rule violations in my Arduino shield project?

Ou:

I'm working on the temperature sensor circuit. Can you identify what patterns it uses?

O LLM entenderá sua intenção e solicitará as informações relevantes do Servidor MCP KiCad. Se precisar de esclarecimentos sobre qual projeto você está se referindo, ele perguntará.

Documentação

Documentação detalhada para cada recurso está disponível no diretório docs/:

Configuração

O Servidor MCP KiCad pode ser configurado usando variáveis de ambiente ou um arquivo .env:

Principais Opções de Configuração

Variável de AmbienteDescriçãoExemplo
KICAD_SEARCH_PATHSLista separada por vírgulas de diretórios para buscar projetos KiCad~/pcb,~/Electronics,~/Projects
KICAD_USER_DIRSubstitui o diretório de usuário padrão do KiCad~/Documents/KiCadProjects
KICAD_APP_PATHSubstitui o caminho padrão do aplicativo KiCad/Applications/KiCad7/KiCad.app

Consulte o Guia de Configuração para mais detalhes.

Guia de Desenvolvimento

Estrutura do Projeto

O Servidor MCP KiCad é organizado em uma estrutura modular:

kicad-mcp/
├── README.md                       # Project documentation
├── main.py                         # Entry point that runs the server
├── requirements.txt                # Python dependencies
├── .env.example                    # Example environment configuration
├── kicad_mcp/                      # Main package directory
│   ├── __init__.py
│   ├── server.py                   # MCP server setup
│   ├── config.py                   # Configuration constants and settings
│   ├── context.py                  # Lifespan management and shared context
│   ├── resources/                  # Resource handlers
│   ├── tools/                      # Tool handlers
│   ├── prompts/                    # Prompt templates
│   └── utils/                      # Utility functions
├── docs/                           # Documentation
└── tests/                          # Unit tests

Adicionando Novos Recursos

Para adicionar novos recursos ao Servidor MCP KiCad, siga estes passos:

  1. Identifique a categoria para seu recurso (recurso, ferramenta ou prompt)
  2. Adicione sua implementação ao módulo apropriado
  3. Registre seu recurso na função de registro correspondente
  4. Teste suas alterações com as ferramentas de desenvolvimento

Consulte o Guia de Desenvolvimento para mais detalhes.

Solução de Problemas

Se você encontrar problemas:

  1. Servidor Não Aparece no Cliente MCP:

    • Verifique se há erros no arquivo de configuração do seu cliente
    • Certifique-se de que o caminho para seu projeto e interpretador Python está correto
    • Garanta que o Python possa acessar o pacote mcp
    • Verifique se sua instalação do KiCad foi detectada

  2. Erros do Servidor:

    • Verifique a saída do terminal ao executar o servidor em modo de desenvolvimento
    • Verifique os logs do Claude em:
      • ~/Library/Logs/Claude/mcp-server-kicad.log (logs específicos do servidor)
      • ~/Library/Logs/Claude/mcp.log (logs gerais do MCP)

  3. Problemas com o Diretório de Trabalho:

    • O diretório de trabalho para servidores iniciados via configurações do cliente pode ser indefinido
    • Sempre use caminhos absolutos em sua configuração e arquivos .env
    • Para testar servidores via linha de comando, o diretório de trabalho será onde você executar o comando

Consulte o Guia de Solução de Problemas para mais detalhes.

Se você ainda não conseguir solucionar o problema, por favor, abra uma issue no Github.

Contribuindo

Quer contribuir para o Servidor MCP KiCad? Veja como você pode ajudar a melhorar este projeto:

  1. Faça um fork do repositório
  2. Crie um branch de recurso
  3. Adicione suas alterações
  4. Envie um pull request

Áreas-chave para contribuição:

  • Adicionar suporte para mais padrões de componentes no sistema de Reconhecimento de Padrões de Circuito
  • Melhorar a documentação e exemplos
  • Adicionar novos recursos ou aprimorar os existentes
  • Corrigir bugs e melhorar o tratamento de erros

Consulte CONTRIBUTING.md para diretrizes detalhadas de contribuição.

Ideias para Desenvolvimento Futuro

Interessado em contribuir? Aqui estão algumas ideias para desenvolvimento futuro:

  1. Visualização de Modelos 3D - Implementar ferramentas para visualizar modelos 3D de PCBs
  2. Ferramentas de Revisão de PCB - Criar recursos de anotação para revisões de design
  3. Geração de Arquivos de Fabricação - Adicionar suporte para gerar arquivos Gerber e outras saídas de fabricação
  4. Busca de Componentes - Implementar funcionalidade de busca para componentes nas bibliotecas do KiCad
  5. Aprimoramento de BOM - Adicionar integração com fornecedores para sourcing e preços de componentes
  6. Verificações de Design Interativas - Desenvolver ferramentas interativas para verificar a qualidade do design
  7. Interface Web - Criar uma interface web simples para configuração e monitoramento
  8. Análise de Circuito - Adicionar recursos de análise de circuito automatizada
  9. Cobertura de Testes - Melhorar a cobertura de testes em todo o código
  10. Reconhecimento de Padrões de Circuito - Expandir o banco de dados de padrões com mais tipos de componentes e topologias de circuito

Licença

Este projeto é open source sob a licença MIT.