Project Management

The project management tools let you find KiCad projects on your system, inspect their file structure, open them in KiCad, and validate their integrity.

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

Listing projects

Could you list all my KiCad projects?

This scans your configured directories and returns a sorted list with project names, file paths, and last-modified dates. Most recently modified projects appear first.

How project discovery works

Projects are discovered by:

1. Looking in the KiCad user directory (KICAD_USER_DIR)
2. Searching directories from KICAD_SEARCH_PATHS
3. Checking common project locations (auto-detected)

Any file with a .kicad_pro extension is treated as a project.

Viewing project details

Show me details about my KiCad project at /path/to/your/project.kicad_pro

Returns:

• Basic project information
• Associated files (schematic, PCB, netlist, BOM exports)
• Project settings and 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

Can you open my KiCad project at /path/to/your/project.kicad_pro?

Launches KiCad with the specified project using platform-appropriate commands (open on macOS, xdg-open on Linux, start on Windows). Requires KiCad to be installed in a standard location or configured via KICAD_APP_PATH.

Validating projects

Validate my KiCad project at /path/to/your/project.kicad_pro

Checks for:

• Missing or corrupt project files
• Required components (schematic, PCB)
• Valid project structure
• Proper JSON formatting

Useful for catching file issues before opening in KiCad.

MCP resources

The server also exposes project data as MCP resources:

• kicad://projects — list of all discovered projects
• kicad://project/{project_path} — details about a specific project

These resources can be accessed programmatically by other MCP clients.

Best practices

1. Use consistent naming — keep project filenames meaningful and predictable
2. Organize by function — group related projects in themed directories
3. Use version control — track project changes with git
4. Use absolute paths — when specifying project paths, absolute paths avoid ambiguity
5. Escape spaces — on all platforms, ensure paths with spaces are properly quoted

Troubleshooting

Projects not found

1. Check .env to ensure KICAD_SEARCH_PATHS includes the right directories
2. Verify projects have the .kicad_pro extension
3. Check read permissions on the directories
4. Try absolute paths instead of relative paths
5. Restart the server after changing configuration

Cannot open projects

1. Verify KiCad is installed
2. Set KICAD_APP_PATH if KiCad is in a non-standard location
3. Ensure the project path is correct and accessible
4. Check the server logs for errors