Servidor KiCad MCP

⚠️ ADVERTENCIA : Este proyecto se creó rápidamente y, en gran parte, no se ha probado. Puede haber fallos. Úselo bajo su propia responsabilidad. Planeo mejorarlo con el tiempo, pero si encuentra errores, abra una incidencia o envíe una solicitud de extracción para corregirlos (consulte la sección "Contribuciones" más abajo).

⚠️ ADVERTENCIA : Este proyecto está optimizado para Mac. Si bien existe cierto soporte básico para Windows y Linux, no se garantiza que todas las funciones funcionen.

Esta guía le ayudará a configurar un servidor MCP (Protocolo de Contexto de Modelo) para KiCad. Si bien los ejemplos de esta guía suelen hacer referencia a Claude Desktop, el servidor es compatible con cualquier cliente compatible con MCP . Puede usarlo con Claude Desktop, sus propios clientes MCP personalizados o cualquier otra aplicación que implemente el MCP.

Prerrequisitos

macOS, Windows o Linux con KiCad instalado
Python 3.10 o superior
KiCad 9.0 o superior
Claude Desktop (u otro cliente MCP)
Familiaridad básica con el terminal

Pasos de instalación

1. Configure su entorno de Python

Primero, instalemos las dependencias y configuremos nuestro entorno:

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

# Create a virtual environment and activate it
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install the MCP SDK and other dependencies
pip install -r requirements.txt

2. Configure su entorno

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

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

# Edit the .env file
vim .env

En el archivo .env , agregue sus directorios de proyecto personalizados:

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

3. Ejecute el servidor

Una vez configurado el entorno, puedes ejecutar el servidor:

# Run in development mode
python -m mcp.dev main.py

# Or run directly
python main.py

4. Configurar un cliente MCP

Ahora, configuremos Claude Desktop para usar nuestro servidor MCP:

Cree o edite 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

Agregue 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"
            ]
        }
    }
}

Reemplace /ABSOLUTE/PATH/TO/YOUR/PROJECT/kicad-mcp con la ruta real al directorio de su proyecto.

5. Reinicie su cliente MCP

Cierre y vuelva a abrir su cliente MCP para cargar la nueva configuración.

Comprensión de los componentes MCP

El Protocolo de Contexto de Modelo (MCP) define tres formas principales de proporcionar capacidades:

Recursos vs. Herramientas vs. Indicaciones

Los recursos son fuentes de datos de solo lectura a las que los LLM pueden hacer referencia:

Similar a los puntos finales GET en las API REST
Proporcionar datos sin realizar cálculos significativos
Se utiliza cuando el LLM necesita leer información
Generalmente, la aplicación cliente accede mediante programación.
Ejemplo: kicad://projects devuelve una lista de todos los proyectos de KiCad

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

Similar a los puntos finales POST/PUT en las API REST
Puede tener efectos secundarios (como abrir aplicaciones o generar archivos)
Se utiliza cuando el LLM necesita realizar acciones en el mundo.
Generalmente invocado directamente por el LLM (con la aprobación del usuario)
Ejemplo: open_project() lanza KiCad con un proyecto específico

Los avisos son plantillas reutilizables para interacciones comunes:

Iniciadores de conversación o instrucciones predefinidos
Ayudar a los usuarios a articular preguntas o tareas comunes
Se invoca por elección del usuario (normalmente desde un menú)
Ejemplo: El mensaje debug_pcb_issues ayuda a los usuarios a solucionar problemas de PCB

Características destacadas

El servidor KiCad MCP ofrece varias funciones clave, cada una con documentación detallada:

Gestión de proyectos : enumerar, examinar y abrir proyectos de KiCad
- Ejemplo: "Muéstrame todos mis proyectos recientes de KiCad" → Enumera todos los proyectos ordenados por fecha de modificación
Análisis de diseño de PCB : obtenga información sobre sus diseños y esquemas de PCB
- Ejemplo: "Analizar la densidad de componentes de mi placa de sensor de temperatura" → Proporciona un análisis del espaciado de los componentes
Extracción de listas de conexiones : extraiga y analice las conexiones de componentes de los esquemas
- Ejemplo: "¿Qué componentes están conectados al MCU en mi shield Arduino?" → Muestra todas las conexiones al microcontrolador
Gestión de listas de materiales : analice y exporte listas de materiales
- Ejemplo: "Generar una lista de materiales para mi proyecto de reloj inteligente" → Crea una lista de materiales detallada
- Comprobación de reglas de diseño : ejecute comprobaciones de DRC y realice un seguimiento de su progreso a lo largo del tiempo
- Ejemplo: "Ejecutar DRC en mi placa de fuente de alimentación y comparar con la semana pasada" → Muestra el progreso en la corrección de las infracciones
- Compatible con KiCad 9.0+: utiliza la nueva CLI de KiCad o la API de IPC automáticamente
Visualización de PCB : genere representaciones visuales de sus diseños de PCB
- Ejemplo: "Muéstrame una miniatura de la PCB de mi amplificador de audio" → Muestra una representación visual de la placa
Reconocimiento de patrones de circuitos : identifique automáticamente patrones de circuitos comunes en sus esquemas
- Ejemplo: "¿Qué topologías de suministro de energía estoy usando en mi dispositivo IoT?" → Identifica reguladores reductores, elevadores o lineales

Para obtener más ejemplos y detalles sobre cada función, consulte las guías dedicadas en la documentación.

Interacción en lenguaje natural

Si bien nuestra documentación a menudo muestra ejemplos como:

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

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

Por ejemplo, en lugar de la orden formal anterior, puedes simplemente preguntar:

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

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

El LLM comprenderá su intención y solicitará la información pertinente al servidor KiCad MCP. Si necesita aclaración sobre el proyecto al que se refiere, la solicitará.

Documentación

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

Configuración

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

Opciones de configuración de claves

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`	Anular el directorio de usuarios predeterminado de KiCad	`~/Documents/KiCadProjects`
`KICAD_APP_PATH`	Anular la ruta de la aplicación KiCad predeterminada	`/Applications/KiCad7/KiCad.app`

Consulte 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

Añadiendo nuevas funciones

Para agregar nuevas funciones al servidor KiCad MCP, siga estos pasos:

Identifique la categoría de su función (recurso, herramienta o solicitud)
Añade tu implementación al módulo apropiado
Registra tu función en la función de registro correspondiente
Pruebe sus cambios con las herramientas de desarrollo

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

Solución de problemas

Si encuentra problemas:

El servidor no aparece en el cliente MCP:
- Verifique el archivo de configuración de su cliente para detectar errores
- Asegúrese de que la ruta a su proyecto y al intérprete de Python sean correctos
- Asegúrese de que Python pueda acceder al paquete mcp
- Comprueba si se detecta tu instalación de KiCad
Errores del servidor:
- Compruebe la salida del terminal al ejecutar el servidor en modo de desarrollo
- Consulte 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)
Problemas con el directorio de trabajo:
- El directorio de trabajo de los servidores iniciados a través de configuraciones de cliente puede no estar definido
- Utilice siempre rutas absolutas en sus archivos de configuración y .env
- Para probar servidores a través de la línea de comandos, el directorio de trabajo será donde ejecute el comando.

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

Contribuyendo

¿Quieres contribuir al servidor KiCad MCP? Puedes ayudar a mejorar este proyecto de la siguiente manera:

Bifurcar el repositorio
Crear una rama de características
Añade tus cambios
Enviar una solicitud de extracción

Áreas clave de contribución:

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 funciones o mejorar las existentes
Corrección de errores y mejora del manejo de errores

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

Ideas de desarrollo futuro

¿Te interesa contribuir? Aquí tienes algunas ideas para el desarrollo futuro:

Visualización de modelos 3D : Implementar herramientas para visualizar modelos 3D de PCB
Herramientas de revisión de PCB : cree funciones de anotación para revisiones de diseño
Generación de archivos de fabricación : agregue soporte para generar archivos Gerber y otras salidas de fabricación
Búsqueda de componentes : implemente la funcionalidad de búsqueda de componentes en las bibliotecas de KiCad
Mejora de la lista de materiales : agregue integración de proveedores para el abastecimiento y la fijación de precios de componentes
Comprobaciones de diseño interactivas : desarrolle herramientas interactivas para comprobar la calidad del diseño
Interfaz web : cree una interfaz web sencilla para la configuración y la supervisión
Análisis de circuitos : agregue funciones de análisis de circuitos automatizados
Cobertura de pruebas : mejore la cobertura de pruebas en toda la base de código
Reconocimiento de patrones de circuitos : amplíe 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.

KiCad MCP Server

Integrations