KiCad MCP Server

Instructions

Implementation Reference

• kicad_mcp/tools/netlist_tools.py:278-442 (handler)

  The primary handler function for the 'find_component_connections' tool. It locates the schematic file, extracts the netlist, identifies the component's pins and connected nets, categorizes pin types, and returns detailed connection information.

  @mcp.tool()
  async def find_component_connections(project_path: str, component_ref: str, ctx: Context | None) -> Dict[str, Any]:
      """Find all connections for a specific component in a KiCad project.
      
      This tool extracts information about how a specific component
      is connected to other components in the schematic.
      
      Args:
          project_path: Path to the KiCad project file (.kicad_pro)
          component_ref: Component reference (e.g., "R1", "U3")
          ctx: MCP context for progress reporting
          
      Returns:
          Dictionary with component connection information
      """
      print(f"Finding connections for component {component_ref} in project: {project_path}")
      
      if not os.path.exists(project_path):
          print(f"Project not found: {project_path}")
          if ctx:
              ctx.info(f"Project not found: {project_path}")
          return {"success": False, "error": f"Project not found: {project_path}"}
      
      # Report progress
      if ctx:
          await ctx.report_progress(10, 100)
      
      # Get the schematic file
      try:
          files = get_project_files(project_path)
          
          if "schematic" not in files:
              print("Schematic file not found in project")
              if ctx:
                  ctx.info("Schematic file not found in project")
              return {"success": False, "error": "Schematic file not found in project"}
          
          schematic_path = files["schematic"]
          print(f"Found schematic file: {schematic_path}")
          if ctx:
              ctx.info(f"Found schematic file: {os.path.basename(schematic_path)}")
          
          # Extract netlist
          if ctx:
              await ctx.report_progress(30, 100)
              ctx.info(f"Extracting netlist to find connections for {component_ref}...")
          
          netlist_data = extract_netlist(schematic_path)
          
          if "error" in netlist_data:
              print(f"Failed to extract netlist: {netlist_data['error']}")
              if ctx:
                  ctx.info(f"Failed to extract netlist: {netlist_data['error']}")
              return {"success": False, "error": netlist_data['error']}
          
          # Check if component exists in the netlist
          components = netlist_data.get("components", {})
          if component_ref not in components:
              print(f"Component {component_ref} not found in schematic")
              if ctx:
                  ctx.info(f"Component {component_ref} not found in schematic")
              return {
                  "success": False, 
                  "error": f"Component {component_ref} not found in schematic",
                  "available_components": list(components.keys())
              }
          
          # Get component information
          component_info = components[component_ref]
          
          # Find connections
          if ctx:
              await ctx.report_progress(50, 100)
              ctx.info("Finding connections...")
          
          nets = netlist_data.get("nets", {})
          connections = []
          connected_nets = []
          
          for net_name, pins in nets.items():
              # Check if any pin belongs to our component
              component_pins = []
              for pin in pins:
                  if pin.get('component') == component_ref:
                      component_pins.append(pin)
                      
              if component_pins:
                  # This net has connections to our component
                  net_connections = []
                  
                  for pin in component_pins:
                      pin_num = pin.get('pin', 'Unknown')
                      # Find other components connected to this pin
                      connected_components = []
                      
                      for other_pin in pins:
                          other_comp = other_pin.get('component')
                          if other_comp and other_comp != component_ref:
                              connected_components.append({
                                  "component": other_comp,
                                  "pin": other_pin.get('pin', 'Unknown')
                              })
                      
                      net_connections.append({
                          "pin": pin_num,
                          "net": net_name,
                          "connected_to": connected_components
                      })
                  
                  connections.extend(net_connections)
                  connected_nets.append(net_name)
          
          # Analyze the connections
          if ctx:
              await ctx.report_progress(70, 100)
              ctx.info("Analyzing connections...")
          
          # Categorize connections by pin function (if possible)
          pin_functions = {}
          if "pins" in component_info:
              for pin in component_info["pins"]:
                  pin_num = pin.get('num')
                  pin_name = pin.get('name', '')
                  
                  # Try to categorize based on pin name
                  pin_type = "unknown"
                  
                  if any(power_term in pin_name.upper() for power_term in ["VCC", "VDD", "VEE", "VSS", "GND", "PWR", "POWER"]):
                      pin_type = "power"
                  elif any(io_term in pin_name.upper() for io_term in ["IO", "I/O", "GPIO"]):
                      pin_type = "io"
                  elif any(input_term in pin_name.upper() for input_term in ["IN", "INPUT"]):
                      pin_type = "input"
                  elif any(output_term in pin_name.upper() for output_term in ["OUT", "OUTPUT"]):
                      pin_type = "output"
                  
                  pin_functions[pin_num] = {
                      "name": pin_name,
                      "type": pin_type
                  }
          
          # Build result
          result = {
              "success": True,
              "project_path": project_path,
              "schematic_path": schematic_path,
              "component": component_ref,
              "component_info": component_info,
              "connections": connections,
              "connected_nets": connected_nets,
              "pin_functions": pin_functions,
              "total_connections": len(connections)
          }
          
          if ctx:
              await ctx.report_progress(100, 100)
              ctx.info(f"Found {len(connections)} connections for component {component_ref}")
          
          return result
          
      except Exception as e:
          print(f"Error finding component connections: {str(e)}", exc_info=True)
          if ctx:
              ctx.info(f"Error finding component connections: {str(e)}")
          return {"success": False, "error": str(e)}

• kicad_mcp/server.py:154-154 (registration)

  The server initialization calls register_netlist_tools(mcp), which defines and registers the find_component_connections tool using @mcp.tool() decorator.

  register_netlist_tools(mcp)

• kicad_mcp/utils/netlist_parser.py:393-393 (helper)

  Helper function used by the tool to parse the schematic and extract netlist data including components and nets.

  def extract_netlist(schematic_path: str) -> Dict[str, Any]: