KiCad MCP Server

Instructions

Implementation Reference

• kicad_mcp/tools/project_tools.py:22-28 (handler)

  The main handler function for the 'list_projects' tool, decorated with @mcp.tool(). It calls find_kicad_projects() and returns the list of projects.
  @mcp.tool() def list_projects() -> List[Dict[str, Any]]: """Find and list all KiCad projects on this system.""" logging.info(f"Executing list_projects tool...") projects = find_kicad_projects() logging.info(f"list_projects tool returning {len(projects)} projects.") return projects
• kicad_mcp/server.py:149-149 (registration)

  The call to register_project_tools which registers the list_projects tool among others.
  register_project_tools(mcp)
• kicad_mcp/utils/kicad_utils.py:15-73 (helper)

  The core helper function find_kicad_projects() that scans configured directories for KiCad project files (.kicad_pro) and returns a list of project dictionaries.
  def find_kicad_projects() -> List[Dict[str, Any]]: """Find KiCad projects in the user's directory. Returns: List of dictionaries with project information """ projects = [] logging.info("Attempting to find KiCad projects...") # Log start # Search directories to look for KiCad projects raw_search_dirs = [config.KICAD_USER_DIR] + config.ADDITIONAL_SEARCH_PATHS logging.info(f"Raw KICAD_USER_DIR: '{config.KICAD_USER_DIR}'") logging.info(f"Raw ADDITIONAL_SEARCH_PATHS: {config.ADDITIONAL_SEARCH_PATHS}") logging.info(f"Raw search list before expansion: {raw_search_dirs}") expanded_search_dirs = [] for raw_dir in raw_search_dirs: expanded_dir = os.path.expanduser(raw_dir) # Expand ~ and ~user if expanded_dir not in expanded_search_dirs: expanded_search_dirs.append(expanded_dir) else: logging.info(f"Skipping duplicate expanded path: {expanded_dir}") logging.info(f"Expanded search directories: {expanded_search_dirs}") for search_dir in expanded_search_dirs: if not os.path.exists(search_dir): logging.warning(f"Expanded search directory does not exist: {search_dir}") # Use warning level continue logging.info(f"Scanning expanded directory: {search_dir}") # Use followlinks=True to follow symlinks if needed for root, _, files in os.walk(search_dir, followlinks=True): for file in files: if file.endswith(config.KICAD_EXTENSIONS["project"]): project_path = os.path.join(root, file) # Check if it's a real file and not a broken symlink if not os.path.isfile(project_path): logging.info(f"Skipping non-file/broken symlink: {project_path}") continue try: # Attempt to get modification time to ensure file is accessible mod_time = os.path.getmtime(project_path) rel_path = os.path.relpath(project_path, search_dir) project_name = get_project_name_from_path(project_path) logging.info(f"Found accessible KiCad project: {project_path}") projects.append({ "name": project_name, "path": project_path, "relative_path": rel_path, "modified": mod_time }) except OSError as e: logging.error(f"Error accessing project file {project_path}: {e}") # Use error level continue # Skip if we can't access it logging.info(f"Found {len(projects)} KiCad projects after scanning.") return projects
• kicad_mcp/tools/project_tools.py:15-20 (registration)

  The registration function that defines and registers the project tools including list_projects via @mcp.tool() decorators.
  def register_project_tools(mcp: FastMCP) -> None: """Register project management tools with the MCP server. Args: mcp: The FastMCP server instance """