KiCad MCP Server

Servidor KiCad MCP

Esta guía te ayudará a configurar un servidor de Model Context Protocol (MCP) para KiCad. Aunque los ejemplos de esta guía suelen hacer referencia a Claude Desktop, el servidor es compatible con cualquier cliente compatible con MCP. Puedes usarlo con Claude Desktop, tus propios clientes MCP personalizados o cualquier otra aplicación que implemente el Model Context Protocol.

Tabla de contenidos

• Requisitos previos
• Pasos de instalación
• Comprensión de los componentes de MCP
• Características destacadas
• Interacción en lenguaje natural
• Documentación
• Configuración
• Guía de desarrollo
• Solución de problemas
• Contribuciones
• Ideas de desarrollo futuro
• Licencia

Requisitos previos

• macOS, Windows o Linux
• Python 3.10 o superior
• KiCad 9.0 o superior
• uv 0.8.0 o superior
• Claude Desktop (u otro cliente MCP)

Pasos de instalación

1. Configura tu entorno de Python

Primero, instalemos las dependencias y configuremos nuestro entorno:

# 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. Configura tu entorno

Crea un archivo .env para personalizar dónde busca el servidor tus proyectos de KiCad:

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

# Edit the .env file
vim .env

En el archivo .env, agrega tus directorios de proyectos personalizados:

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

3. Ejecuta el servidor

Una vez que el entorno esté configurado, puedes ejecutar el servidor:

python main.py

4. Configura un cliente MCP

Ahora, configuremos Claude Desktop para usar nuestro servidor MCP:

1. Crea o edita el archivo de configuración de 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

2. Agrega el servidor KiCad MCP a la configuración:

{
    "mcpServers": {
        "kicad": {
            "command": "/ABSOLUTE/PATH/TO/YOUR/PROJECT/kicad-mcp/.venv/bin/python",
            "args": [
                "/ABSOLUTE/PATH/TO/YOUR/PROJECT/kicad-mcp/main.py"
            ]
        }
    }
}

Reemplaza /ABSOLUTE/PATH/TO/YOUR/PROJECT/kicad-mcp con la ruta real a tu directorio de proyectos.

5. Reinicia tu cliente MCP

Cierra y vuelve a abrir tu cliente MCP para cargar la nueva configuración.

Comprensión de los componentes de MCP

El Model Context Protocol (MCP) define tres formas principales de proporcionar capacidades:

Recursos vs Herramientas vs Prompts

Los recursos son fuentes de datos de solo lectura que los LLM pueden consultar:

• Similares a los endpoints GET en las API REST
• Proporcionan datos sin realizar cálculos significativos
• Se utilizan cuando el LLM necesita leer información
• Normalmente se accede a ellos mediante programación desde la aplicación cliente
• Ejemplo: kicad://projects devuelve una lista de todos los proyectos de KiCad

Las herramientas son funciones que realizan acciones o cálculos:

• Similares a los endpoints POST/PUT en las API REST
• Pueden tener efectos secundarios (como abrir aplicaciones o generar archivos)
• Se utilizan cuando el LLM necesita realizar acciones en el mundo
• Normalmente las invoca directamente el LLM (con la aprobación del usuario)
• Ejemplo: open_project() inicia KiCad con un proyecto específico

Los prompts son plantillas reutilizables para interacciones comunes:

• Iniciadores de conversación o instrucciones predefinidos
• Ayudan a los usuarios a formular preguntas o tareas comunes
• Se invocan por elección del usuario (normalmente desde un menú)
• Ejemplo: El prompt debug_pcb_issues ayuda a los usuarios a solucionar problemas de PCB

Para obtener más información sobre recursos vs herramientas vs prompts, lee la documentación de MCP.

Características destacadas

El servidor KiCad MCP proporciona varias características clave, cada una con documentación detallada:

• Gestión de proyectos: Lista, examina y abre proyectos de KiCad

  • Ejemplo: "Muéstrame todos mis proyectos recientes de KiCad" → Lista todos los proyectos ordenados por fecha de modificación

• Análisis de diseño de PCB: Obtén información sobre tus diseños de PCB y esquemáticos

  • Ejemplo: "Analiza la densidad de componentes de mi placa de sensor de temperatura" → Proporciona un análisis de espaciado de componentes

• Extracción de netlist: Extrae y analiza las conexiones de componentes de los esquemáticos

  • Ejemplo: "¿Qué componentes están conectados al MCU en mi shield de Arduino?" → Muestra todas las conexiones al microcontrolador

• Gestión de BOM: Analiza y exporta listas de materiales

  • Ejemplo: "Genera un BOM para mi proyecto de reloj inteligente" → Crea una lista de materiales detallada

• Verificación de reglas de diseño: Ejecuta comprobaciones DRC usando la CLI de KiCad y realiza un seguimiento de tu progreso a lo largo del tiempo

  • Ejemplo: "Ejecuta DRC en mi placa de fuente de alimentación y compáralo con la semana pasada" → Muestra el progreso en la corrección de violaciones

• Visualización de PCB: Genera representaciones visuales de tus diseños de PCB

  • Ejemplo: "Muéstrame una miniatura de mi PCB de amplificador de audio" → Muestra una representación visual de la placa

• Reconocimiento de patrones de circuitos: Identifica automáticamente patrones de circuitos comunes en tus esquemáticos

  • Ejemplo: "¿Qué topologías de fuente de alimentación estoy usando en mi dispositivo IoT?" → Identifica reguladores buck, boost o lineales

Para obtener más ejemplos y detalles sobre cada característica, consulta las guías dedicadas en la documentación. ¡También puedes preguntarle al LLM a qué herramientas tiene acceso!

Interacción en lenguaje natural

Aunque nuestra documentación suele mostrar ejemplos como:

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

¡No necesitas escribir la ruta completa a tus archivos! El LLM puede entender solicitudes en lenguaje más natural.

Por ejemplo, en lugar del comando formal anterior, simplemente puedes preguntar:

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

O:

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

El LLM entenderá tu intención y solicitará la información relevante al servidor KiCad MCP. Si necesita aclarar a qué proyecto te refieres, te lo preguntará.

Documentación

La documentación detallada de cada característica está disponible en el directorio docs/:

• Gestión de proyectos
• Análisis de diseño de PCB
• Extracción de netlist
• Lista de materiales (BOM)
• Verificación de reglas de diseño (DRC)
• Visualización de PCB
• Reconocimiento de patrones de circuitos
• Plantillas de prompts

Configuración

El servidor KiCad MCP se puede configurar usando variables de entorno o un archivo .env:

Opciones de configuración clave

Variable de entorno	Descripción	Ejemplo
KICAD_SEARCH_PATHS	Lista de directorios separados por comas para buscar proyectos de KiCad	~/pcb,~/Electronics,~/Projects
KICAD_USER_DIR	Anula el directorio de usuario predeterminado de KiCad	~/Documents/KiCadProjects
KICAD_APP_PATH	Anula la ruta de aplicación predeterminada de KiCad	/Applications/KiCad7/KiCad.app

Consulta la Guía de configuración para obtener más detalles.

Guía de desarrollo

Estructura del proyecto

El servidor KiCad MCP está organizado en una estructura 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

Agregar nuevas características

Para agregar nuevas características al servidor KiCad MCP, sigue estos pasos:

1. Identifica la categoría de tu característica (recurso, herramienta o prompt)
2. Agrega tu implementación al módulo correspondiente
3. Registra tu característica en la función de registro correspondiente
4. Prueba tus cambios con las herramientas de desarrollo

Consulta la Guía de desarrollo para obtener más detalles.

Solución de problemas

Si encuentras problemas:

1. El servidor no aparece en el cliente MCP:

   • Revisa el archivo de configuración de tu cliente para detectar errores
   • Asegúrate de que la ruta a tu proyecto y al intérprete de Python sea correcta
   • Asegúrate de que Python pueda acceder al paquete mcp
   • Verifica si se detecta tu instalación de KiCad

2. Errores del servidor:

   • Revisa la salida del terminal al ejecutar el servidor en modo de desarrollo
   • Revisa los registros de Claude en:
     • ~/Library/Logs/Claude/mcp-server-kicad.log (registros específicos del servidor)
     • ~/Library/Logs/Claude/mcp.log (registros generales de MCP)

3. Problemas con el directorio de trabajo:

   • El directorio de trabajo de los servidores iniciados mediante configuraciones de cliente puede no estar definido
   • Usa siempre rutas absolutas en tu configuración y archivos .env
   • Para probar servidores mediante la línea de comandos, el directorio de trabajo será donde ejecutes el comando

Consulta la Guía de solución de problemas para obtener más detalles.

Si aún no puedes resolver el problema, abre un issue en Github.

Contribuciones

¿Quieres contribuir al servidor KiCad MCP? Así puedes ayudar a mejorar este proyecto:

1. Haz un fork del repositorio
2. Crea una rama de características
3. Agrega tus cambios
4. Envía un pull request

Áreas clave para contribuir:

• Agregar soporte para más patrones de componentes en el sistema de Reconocimiento de patrones de circuitos
• Mejorar la documentación y los ejemplos
• Agregar nuevas características o mejorar las existentes
• Corregir errores y mejorar el manejo de errores

Consulta CONTRIBUTING.md para obtener pautas detalladas de contribución.

Ideas de desarrollo futuro

¿Interesado en contribuir? Aquí tienes algunas ideas para el desarrollo futuro:

1. Visualización de modelos 3D - Implementar herramientas para visualizar modelos 3D de PCB
2. Herramientas de revisión de PCB - Crear funciones de anotación para revisiones de diseño
3. Generación de archivos de fabricación - Agregar soporte para generar archivos Gerber y otras salidas de fabricación
4. Búsqueda de componentes - Implementar funcionalidad de búsqueda de componentes en las bibliotecas de KiCad
5. Mejora de BOM - Agregar integración con proveedores para el abastecimiento y precios de componentes
6. Comprobaciones de diseño interactivas - Desarrollar herramientas interactivas para verificar la calidad del diseño
7. Interfaz web - Crear una interfaz web simple para configuración y monitoreo
8. Análisis de circuitos - Agregar funciones de análisis de circuitos automatizado
9. Cobertura de pruebas - Mejorar la cobertura de pruebas en todo el código base
10. Reconocimiento de patrones de circuitos - Ampliar la base de datos de patrones con más tipos de componentes y topologías de circuitos

Licencia

Este proyecto es de código abierto bajo la licencia MIT.