kicad-mcp/docs/analysis_guide.md

KiCad PCB Design Analysis Guide

This guide explains how to use the PCB design analysis features in the KiCad MCP Server.

Overview

The PCB design analysis functionality allows you to:

1. Extract and analyze information from schematics
2. Validate projects for completeness and correctness
3. Get insights about components and connections
4. Understand PCB layout characteristics

Quick Reference

Task	Example Prompt
Get schematic info	What components are in my schematic at /path/to/project.kicad_sch?
Validate project	Validate my KiCad project at /path/to/project.kicad_pro
Analyze PCB	Analyze the PCB layout at /path/to/project.kicad_pcb

Using PCB Analysis Features

Schematic Information

To extract information from a schematic:

What components are in my schematic at /path/to/project.kicad_sch?

This will provide:

• A list of all components in the schematic
• Component values and footprints
• Connection information
• Basic schematic structure

Example output:

# Schematic: my_project.kicad_sch

## Components (Estimated Count: 42)

(symbol (lib_id "Device:R") (at 127 87.63 0) (unit 1)
(symbol (lib_id "Device:C") (at 142.24 90.17 0) (unit 1)
(symbol (lib_id "MCU_Microchip_ATmega:ATmega328P-PU") (at 170.18 88.9 0) (unit 1)

... and 39 more components

Project Validation

To check a project for issues:

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

The validation checks for:

• Missing project files
• Required components (schematic, PCB)
• Valid file formats
• Common structural issues

This is useful for identifying problems before opening files in KiCad.

PCB Layout Analysis

To analyze a PCB layout:

Analyze the PCB layout at /path/to/project.kicad_pcb

This will provide information about:

• Board dimensions
• Layer structure
• Component placement
• Trace characteristics
• Via usage

Available Resources

The server provides several resources for accessing design information:

• kicad://schematic/{schematic_path} - Information from a schematic file
• kicad://pcb/{pcb_path} - Information from a PCB file

These resources can be accessed programmatically by other MCP clients or directly referenced in conversations.

Tips for Better Analysis

Focus on Specific Elements

You can ask for analysis of specific aspects of your design:

What are all the resistor values in my schematic at /path/to/project.kicad_sch?

Show me all the power connections in my schematic at /path/to/project.kicad_sch

Integration with Other Features

Combine analysis with other features for better insights:

1. Analyze a schematic first to understand component selection
2. Check the BOM for component availability and cost
3. Run DRC checks to find design rule violations
4. View the PCB thumbnail for a visual overview

Common Analysis Tasks

Finding Specific Components

To locate components in your schematic:

Find all decoupling capacitors in my schematic at /path/to/project.kicad_sch

This helps with understanding component usage and ensuring proper design practices.

Identifying Signal Paths

To trace signals through your design:

Trace the clock signal path in my schematic at /path/to/project.kicad_sch

This helps with understanding signal flow and potential issues.

Board Metrics

To get metrics about your PCB:

What are the dimensions of my PCB at /path/to/project.kicad_pcb?

How many vias are in my PCB at /path/to/project.kicad_pcb?

Troubleshooting

Schematic Reading Errors

If the server can't read your schematic:

1. Verify the file exists and has the correct extension (.kicad_sch)
2. Check if the file is a valid KiCad schematic
3. Ensure you have read permissions for the file
4. Try the analysis on a simpler schematic to isolate the issue

PCB Analysis Issues

If PCB analysis fails:

1. Check if the PCB file exists and has the correct extension (.kicad_pcb)
2. Ensure the PCB file is not corrupted
3. Check for complex features that might cause parsing issues
4. Try a simplified PCB to isolate the problem

Advanced Usage

Design Reviews

Use the analysis features for comprehensive design reviews:

Review the power distribution network in my schematic at /path/to/project.kicad_sch

Check my PCB at /path/to/project.kicad_pcb for potential EMI issues

Custom Analysis Scripts

For advanced users:

1. Use the schematic and PCB analysis tools to extract data
2. Ask for specific analytical insights on that data
3. Request recommendations based on the analysis

Limitations

The current analysis capabilities have some limitations:

1. Complexity limits: Very large or complex designs may not be fully analyzed
2. KiCad version compatibility: Best results with the same KiCad version as the server
3. Limited semantic understanding: The analysis is primarily structural rather than functional
4. No simulation capabilities: The server cannot perform electrical simulation

Future Improvements

Future versions of the KiCad MCP Server aim to enhance the analysis capabilities with:

1. More detailed component information extraction
2. Better understanding of circuit functionality
3. Enhanced power and signal analysis
4. Integration with KiCad's ERC and DRC engines
5. Support for hierarchical schematics