KiCad MCP Server

Instructions

Implementation Reference

• kicad_mcp/tools/bom_tools.py:161-247 (handler)

  The primary handler function for the 'export_bom_csv' tool. It orchestrates BOM export by first trying KiCad Python modules and falling back to CLI tools.
  @mcp.tool() async def export_bom_csv(project_path: str, ctx: Context | None) -> Dict[str, Any]: """Export a Bill of Materials for a KiCad project. This tool attempts to generate a CSV BOM file for a KiCad project. It requires KiCad to be installed with the appropriate command-line tools. Args: project_path: Path to the KiCad project file (.kicad_pro) ctx: MCP context for progress reporting Returns: Dictionary with export results """ print(f"Exporting BOM for 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}"} # Get access to the app context app_context = ctx.request_context.lifespan_context if ctx else None kicad_modules_available = app_context.kicad_modules_available if app_context else False # Report progress if ctx: await ctx.report_progress(10, 100) # Get all project files files = get_project_files(project_path) # We need the schematic file to generate a BOM 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"} schematic_file = files["schematic"] project_dir = os.path.dirname(project_path) project_name = os.path.basename(project_path)[:-10] # Remove .kicad_pro extension if ctx: await ctx.report_progress(20, 100) ctx.info(f"Found schematic file: {os.path.basename(schematic_file)}") # Try to export BOM # This will depend on KiCad's command-line tools or Python modules export_result = {"success": False} if kicad_modules_available: try: # Try to use KiCad Python modules if ctx: ctx.info("Attempting to export BOM using KiCad Python modules...") export_result = await export_bom_with_python(schematic_file, project_dir, project_name, ctx) except Exception as e: print(f"Error exporting BOM with Python modules: {str(e)}", exc_info=True) if ctx: ctx.info(f"Error using Python modules: {str(e)}") export_result = {"success": False, "error": str(e)} # If Python method failed, try command-line method if not export_result.get("success", False): try: if ctx: ctx.info("Attempting to export BOM using command-line tools...") export_result = await export_bom_with_cli(schematic_file, project_dir, project_name, ctx) except Exception as e: print(f"Error exporting BOM with CLI: {str(e)}", exc_info=True) if ctx: ctx.info(f"Error using command-line tools: {str(e)}") export_result = {"success": False, "error": str(e)} if ctx: await ctx.report_progress(100, 100) if export_result.get("success", False): if ctx: ctx.info(f"BOM exported successfully to {export_result.get('output_file', 'unknown location')}") else: if ctx: ctx.info(f"Failed to export BOM: {export_result.get('error', 'Unknown error')}") return export_result
• kicad_mcp/server.py:153-153 (registration)

  Top-level registration call in the server creation that invokes register_bom_tools(mcp), which registers the export_bom_csv tool among BOM tools.
  register_bom_tools(mcp)
• kicad_mcp/tools/bom_tools.py:629-787 (helper)

  Key helper function that implements the command-line BOM export using kicad-cli, handling platform differences (Windows, macOS, Linux).
  async def export_bom_with_cli(schematic_file: str, output_dir: str, project_name: str, ctx: Context | None) -> Dict[str, Any]: """Export a BOM using KiCad command-line tools. Args: schematic_file: Path to the schematic file output_dir: Directory to save the BOM project_name: Name of the project ctx: MCP context for progress reporting Returns: Dictionary with export results """ import subprocess import platform system = platform.system() print(f"Exporting BOM using CLI tools on {system}") if ctx: await ctx.report_progress(40, 100) # Output file path output_file = os.path.join(output_dir, f"{project_name}_bom.csv") # Define the command based on operating system if system == "Darwin": # macOS from kicad_mcp.config import KICAD_APP_PATH # Path to KiCad command-line tools on macOS kicad_cli = os.path.join(KICAD_APP_PATH, "Contents/MacOS/kicad-cli") if not os.path.exists(kicad_cli): return { "success": False, "error": f"KiCad CLI tool not found at {kicad_cli}", "schematic_file": schematic_file } # Command to generate BOM cmd = [ kicad_cli, "sch", "export", "bom", "--output", output_file, schematic_file ] elif system == "Windows": from kicad_mcp.config import KICAD_APP_PATH # Path to KiCad command-line tools on Windows kicad_cli = os.path.join(KICAD_APP_PATH, "bin", "kicad-cli.exe") if not os.path.exists(kicad_cli): return { "success": False, "error": f"KiCad CLI tool not found at {kicad_cli}", "schematic_file": schematic_file } # Command to generate BOM cmd = [ kicad_cli, "sch", "export", "bom", "--output", output_file, schematic_file ] elif system == "Linux": # Assume kicad-cli is in the PATH kicad_cli = "kicad-cli" # Command to generate BOM cmd = [ kicad_cli, "sch", "export", "bom", "--output", output_file, schematic_file ] else: return { "success": False, "error": f"Unsupported operating system: {system}", "schematic_file": schematic_file } try: print(f"Running command: {' '.join(cmd)}") if ctx: await ctx.report_progress(60, 100) # Run the command process = subprocess.run(cmd, capture_output=True, text=True, timeout=30) # Check if the command was successful if process.returncode != 0: print(f"BOM export command failed with code {process.returncode}") print(f"Error output: {process.stderr}") return { "success": False, "error": f"BOM export command failed: {process.stderr}", "schematic_file": schematic_file, "command": ' '.join(cmd) } # Check if the output file was created if not os.path.exists(output_file): return { "success": False, "error": "BOM file was not created", "schematic_file": schematic_file, "output_file": output_file } if ctx: await ctx.report_progress(80, 100) # Read the first few lines of the BOM to verify it's valid with open(output_file, 'r') as f: bom_content = f.read(1024) # Read first 1KB if len(bom_content.strip()) == 0: return { "success": False, "error": "Generated BOM file is empty", "schematic_file": schematic_file, "output_file": output_file } return { "success": True, "schematic_file": schematic_file, "output_file": output_file, "file_size": os.path.getsize(output_file), "message": "BOM exported successfully" } except subprocess.TimeoutExpired: print("BOM export command timed out after 30 seconds") return { "success": False, "error": "BOM export command timed out after 30 seconds", "schematic_file": schematic_file } except Exception as e: print(f"Error exporting BOM: {str(e)}", exc_info=True) return { "success": False, "error": f"Error exporting BOM: {str(e)}", "schematic_file": schematic_file }
• kicad_mcp/tools/bom_tools.py:586-627 (helper)

  Helper function for BOM export using KiCad Python modules, called first but falls back to CLI if unavailable.
  async def export_bom_with_python(schematic_file: str, output_dir: str, project_name: str, ctx: Context | None) -> Dict[str, Any]: """Export a BOM using KiCad Python modules. Args: schematic_file: Path to the schematic file output_dir: Directory to save the BOM project_name: Name of the project ctx: MCP context for progress reporting Returns: Dictionary with export results """ print(f"Exporting BOM for schematic: {schematic_file}") if ctx: await ctx.report_progress(30, 100) try: # Try to import KiCad Python modules # This is a placeholder since exporting BOMs from schematic files # is complex and KiCad's API for this is not well-documented import kicad import kicad.pcbnew # For now, return a message indicating this method is not implemented yet print("BOM export with Python modules not fully implemented") if ctx: ctx.info("BOM export with Python modules not fully implemented yet") return { "success": False, "error": "BOM export using Python modules is not fully implemented yet. Try using the command-line method.", "schematic_file": schematic_file } except ImportError: print("Failed to import KiCad Python modules") return { "success": False, "error": "Failed to import KiCad Python modules", "schematic_file": schematic_file }
• kicad_mcp/tools/bom_tools.py:13-247 (registration)

  The register_bom_tools function that defines both BOM tools (analyze_bom and export_bom_csv) with @mcp.tool() decorators for registration.
  def register_bom_tools(mcp: FastMCP) -> None: """Register BOM-related tools with the MCP server. Args: mcp: The FastMCP server instance """ @mcp.tool() async def analyze_bom(project_path: str, ctx: Context | None) -> Dict[str, Any]: """Analyze a KiCad project's Bill of Materials. This tool will look for BOM files related to a KiCad project and provide analysis including component counts, categories, and cost estimates if available. Args: project_path: Path to the KiCad project file (.kicad_pro) ctx: MCP context for progress reporting Returns: Dictionary with BOM analysis results """ print(f"Analyzing BOM for 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) ctx.info(f"Looking for BOM files related to {os.path.basename(project_path)}") # Get all project files files = get_project_files(project_path) # Look for BOM files bom_files = {} for file_type, file_path in files.items(): if "bom" in file_type.lower() or file_path.lower().endswith(".csv"): bom_files[file_type] = file_path print(f"Found potential BOM file: {file_path}") if not bom_files: print("No BOM files found for project") if ctx: ctx.info("No BOM files found for project") return { "success": False, "error": "No BOM files found. Export a BOM from KiCad first.", "project_path": project_path } if ctx: await ctx.report_progress(30, 100) # Analyze each BOM file results = { "success": True, "project_path": project_path, "bom_files": {}, "component_summary": {} } total_unique_components = 0 total_components = 0 for file_type, file_path in bom_files.items(): try: if ctx: ctx.info(f"Analyzing {os.path.basename(file_path)}") # Parse the BOM file bom_data, format_info = parse_bom_file(file_path) if not bom_data or len(bom_data) == 0: print(f"Failed to parse BOM file: {file_path}") continue # Analyze the BOM data analysis = analyze_bom_data(bom_data, format_info) # Add to results results["bom_files"][file_type] = { "path": file_path, "format": format_info, "analysis": analysis } # Update totals total_unique_components += analysis["unique_component_count"] total_components += analysis["total_component_count"] print(f"Successfully analyzed BOM file: {file_path}") except Exception as e: print(f"Error analyzing BOM file {file_path}: {str(e)}", exc_info=True) results["bom_files"][file_type] = { "path": file_path, "error": str(e) } if ctx: await ctx.report_progress(70, 100) # Generate overall component summary if total_components > 0: results["component_summary"] = { "total_unique_components": total_unique_components, "total_components": total_components } # Calculate component categories across all BOMs all_categories = {} for file_type, file_info in results["bom_files"].items(): if "analysis" in file_info and "categories" in file_info["analysis"]: for category, count in file_info["analysis"]["categories"].items(): if category not in all_categories: all_categories[category] = 0 all_categories[category] += count results["component_summary"]["categories"] = all_categories # Calculate total cost if available total_cost = 0.0 cost_available = False for file_type, file_info in results["bom_files"].items(): if "analysis" in file_info and "total_cost" in file_info["analysis"]: if file_info["analysis"]["total_cost"] > 0: total_cost += file_info["analysis"]["total_cost"] cost_available = True if cost_available: results["component_summary"]["total_cost"] = round(total_cost, 2) currency = next(( file_info["analysis"].get("currency", "USD") for file_type, file_info in results["bom_files"].items() if "analysis" in file_info and "currency" in file_info["analysis"] ), "USD") results["component_summary"]["currency"] = currency if ctx: await ctx.report_progress(100, 100) ctx.info(f"BOM analysis complete: found {total_components} components") return results @mcp.tool() async def export_bom_csv(project_path: str, ctx: Context | None) -> Dict[str, Any]: """Export a Bill of Materials for a KiCad project. This tool attempts to generate a CSV BOM file for a KiCad project. It requires KiCad to be installed with the appropriate command-line tools. Args: project_path: Path to the KiCad project file (.kicad_pro) ctx: MCP context for progress reporting Returns: Dictionary with export results """ print(f"Exporting BOM for 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}"} # Get access to the app context app_context = ctx.request_context.lifespan_context if ctx else None kicad_modules_available = app_context.kicad_modules_available if app_context else False # Report progress if ctx: await ctx.report_progress(10, 100) # Get all project files files = get_project_files(project_path) # We need the schematic file to generate a BOM 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"} schematic_file = files["schematic"] project_dir = os.path.dirname(project_path) project_name = os.path.basename(project_path)[:-10] # Remove .kicad_pro extension if ctx: await ctx.report_progress(20, 100) ctx.info(f"Found schematic file: {os.path.basename(schematic_file)}") # Try to export BOM # This will depend on KiCad's command-line tools or Python modules export_result = {"success": False} if kicad_modules_available: try: # Try to use KiCad Python modules if ctx: ctx.info("Attempting to export BOM using KiCad Python modules...") export_result = await export_bom_with_python(schematic_file, project_dir, project_name, ctx) except Exception as e: print(f"Error exporting BOM with Python modules: {str(e)}", exc_info=True) if ctx: ctx.info(f"Error using Python modules: {str(e)}") export_result = {"success": False, "error": str(e)} # If Python method failed, try command-line method if not export_result.get("success", False): try: if ctx: ctx.info("Attempting to export BOM using command-line tools...") export_result = await export_bom_with_cli(schematic_file, project_dir, project_name, ctx) except Exception as e: print(f"Error exporting BOM with CLI: {str(e)}", exc_info=True) if ctx: ctx.info(f"Error using command-line tools: {str(e)}") export_result = {"success": False, "error": str(e)} if ctx: await ctx.report_progress(100, 100) if export_result.get("success", False): if ctx: ctx.info(f"BOM exported successfully to {export_result.get('output_file', 'unknown location')}") else: if ctx: ctx.info(f"Failed to export BOM: {export_result.get('error', 'Unknown error')}") return export_result