KiCad MCP Server

# KiCad Project Management Guide This guide explains how to use the project management features in the KiCad MCP Server. ## Overview The project management functionality allows you to: 1. List all KiCad projects on your system 2. View detailed information about specific projects 3. Open projects directly in KiCad 4. Validate project files for completeness and correctness ## Quick Reference | Task | Example Prompt | |------|---------------| | List all projects | `List all my KiCad projects` | | View project details | `Show details for my KiCad project at /path/to/project.kicad_pro` | | Open a project | `Open my KiCad project at /path/to/project.kicad_pro` | | Validate a project | `Validate my KiCad project at /path/to/project.kicad_pro` | ## Using Project Management Features ### Listing Projects To see all KiCad projects available on your system: ``` Could you list all my KiCad projects? ``` This will: - Search your KiCad user directory (typically `~/Documents/KiCad`) - Search any additional directories specified in your configuration - Display a formatted list of projects with: - Project names - File paths - Last modified dates The listing is sorted by last modified date, with most recently modified projects first. #### How Project Discovery Works Projects are discovered by: 1. Looking in the standard KiCad user directory 2. Searching directories specified in the `KICAD_SEARCH_PATHS` environment variable 3. Looking in common project directories (automatically detected) ### Viewing Project Details To get detailed information about a specific project: ``` Show me details about my KiCad project at /path/to/your/project.kicad_pro ``` This will display: - Basic project information - Associated files (schematic, PCB, etc.) - Project settings - Metadata Example output: ``` # Project: my_project ## Project Files - **project**: /path/to/my_project.kicad_pro - **schematic**: /path/to/my_project.kicad_sch - **pcb**: /path/to/my_project.kicad_pcb - **netlist**: /path/to/my_project_netlist.net ## Project Settings - **version**: 20210606 - **generator**: pcbnew - **board_thickness**: 1.6 ``` ### Opening Projects To open a KiCad project: ``` Can you open my KiCad project at /path/to/your/project.kicad_pro? ``` This will: - Launch KiCad with the specified project - Return confirmation and status information Note that this requires KiCad to be properly installed in the standard location for your operating system. The server detects KiCad's location automatically based on your platform. ### Validating Projects To validate a KiCad project for issues: ``` Validate my KiCad project at /path/to/your/project.kicad_pro ``` The validation will check for: - Missing or corrupt project files - Required components (schematic, PCB) - Valid project structure - Proper JSON formatting This is useful for identifying issues with project files before attempting to open them in KiCad. ## Project Resources The server provides several resources for accessing project information: - `kicad://projects` - List of all projects - `kicad://project/{project_path}` - Details about a specific project These resources can be accessed programmatically by other MCP clients or directly referenced in conversations. ## Tips for Project Management ### Best Practices For smooth project management: 1. **Use consistent naming**: Keep project filenames consistent and meaningful 2. **Organize by functionality**: Group related projects in themed directories 3. **Include documentation**: Add README files or documentation in project directories 4. **Back up regularly**: Create backups of important projects 5. **Use version control**: Consider using git for tracking project changes ### Path Handling When specifying project paths: - Use absolute paths for reliability - Ensure paths are properly escaped if they contain spaces - On Windows, use forward slashes (/) instead of backslashes (\\) ## Troubleshooting ### Projects Not Found If your projects aren't being discovered: 1. Check your `.env` file to ensure search paths are correctly specified 2. Verify that projects have the `.kicad_pro` extension 3. Check if you have read permissions for the specified directories 4. Try using absolute paths instead of relative paths 5. Restart the server after changing configuration ### Can't Open Projects If you can't open projects: 1. Verify that KiCad is installed correctly 2. Check the `KICAD_APP_PATH` configuration if KiCad is in a non-standard location 3. Ensure the project path is correctly specified and accessible 4. Check if you have permissions to launch applications 5. Look for errors in the server logs ## Advanced Usage ### Custom Project Queries You can ask more specific questions about your projects: ``` Which of my KiCad projects were modified in the last week? ``` ``` Show me all KiCad projects in my ~/Electronics directory that have a PCB file ``` ### Project Statistics For insights across multiple projects: ``` What's the average board size across all my KiCad projects? ``` ``` Which components are most commonly used across my KiCad projects? ```