gfp-mcp 0.3.2

Model Context Protocol (MCP) server for GDSFactory+ photonic IC design

GDSFactory+ MCP Server

Model Context Protocol (MCP) server for GDSFactory+ that enables AI assistants like Claude to design and build photonic integrated circuits.

What is this?

This MCP server connects AI assistants to GDSFactory+, allowing you to design photonic ICs through natural language. Build components, run verification checks, and manage multiple projects directly from Claude Code or Claude Desktop.

Quick Start

1. Install Prerequisites

• Python 3.10 or higher
• VSCode with the GDSFactory+ extension installed

2. Install the MCP Server

With uv (recommended):

If you don't have uv installed, see the uv installation guide.

uv tool install gfp-mcp

Ephemeral approach

Run without installing:

uvx --from gfp-mcp gfp-mcp-serve

Alternative: pip install

pip install gfp-mcp

3. Connect to Your AI Assistant

Claude Code

Add to .claude/settings.json:

{
    "mcpServers": {
        "gdsfactoryplus": {
            "command": "gfp-mcp-serve",
            "args": [],
            "env": {
                "GFP_API_URL": "http://localhost:8787"
            }
        }
    }
}

Or use the CLI:

claude mcp add gdsfactoryplus -- gfp-mcp-serve

Claude Desktop

Add to your config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Linux: ~/.config/Claude/claude_desktop_config.json

{
    "mcpServers": {
        "gdsfactoryplus": {
            "command": "gfp-mcp-serve",
            "args": []
        }
    }
}

Restart Claude Desktop after adding the configuration.

Cursor

Coming soon. Follow the MCP integration instructions for Cursor when available.

4. Start Designing

The MCP server automatically discovers running GDSFactory+ servers via the registry (~/.gdsfactory/server-registry.json). On startup, it will log all discovered projects.

Try these commands with your AI assistant:

• "List all available photonic components"
• "Build an MZI interferometer"
• "Show me details about the directional coupler"
• "Build multiple components: mzi, coupler, and bend_euler"
• "List all my GDSFactory+ projects"

Available Tools

• build_cells - Build one or more GDS cells by name (pass a list, can be single-item)
• list_cells - List all available photonic components
• get_cell_info - Get detailed component metadata
• list_projects - List all running GDSFactory+ server instances
• get_project_info - Get detailed information about a specific project
• check_drc - Run Design Rule Check verification (returns structured format with all violations including simplified location data for LLM-friendly troubleshooting)
• check_connectivity - Run connectivity verification
• check_lvs - Run Layout vs. Schematic verification
• simulate_component - Run SAX circuit simulations with custom parameters
  • Basic: {"name": "mzi"} - Simulate with default parameters
  • Custom layout: {"name": "mzi", "layout": {"length_mmi": 12, "gap_mmi": 0.3}} - Customize component geometry
  • Wavelength sweep: {"name": "coupler", "model": {"wl": [1.5, 1.55, 1.6]}} - Simulate at multiple wavelengths
  • Full example: {"name": "mzi", "layout": {"length": 100}, "model": {"wl": [1.5, 1.55, 1.6], "loss": 0.2}, "how": "from_layout"}
• get_port_center - Get physical coordinates of component ports
• generate_bbox - Generate bounding box GDS from layout
• freeze_cell - Freeze parametric cell as static netlist
• get_pdk_info - Get current PDK information

Multi-Project Support

The MCP server automatically discovers all running GDSFactory+ projects via the server registry (~/.gdsfactory/server-registry.json). The registry is the source of truth for available servers. Use the list_projects tool to see all running projects, then specify the project name when building components:

User: "List all my GDSFactory+ projects"
Claude: [Uses list_projects tool to show all running servers]

User: "Build the mzi component in my_photonics_project"
Claude: [Routes request to the correct project]

Troubleshooting

Server not appearing in Claude

1. Verify installation: gfp-mcp-serve --help
2. Check Claude Code logs: claude --debug
3. Restart Claude Desktop/Code
4. Ensure the GDSFactory+ VSCode extension is active and a project is open

Connection refused errors

The MCP server uses the registry (~/.gdsfactory/server-registry.json) to discover running servers.

1. Use the list_projects tool in Claude to check available servers
2. If no servers are found, ensure the GDSFactory+ VSCode extension is running with an active project:
   • Open VSCode with the GDSFactory+ extension installed
   • Open a GDSFactory+ project folder
   • The extension automatically starts the server and registers it
3. Check the MCP startup logs for discovered servers
4. Verify the registry is accessible at ~/.gdsfactory/server-registry.json
5. For backward compatibility, you can set a specific server URL:

export GFP_API_URL="http://localhost:YOUR_PORT"

Tool execution timeout

Increase the timeout for long-running operations:

export GFP_MCP_TIMEOUT=600  # 10 minutes