gfp-mcp 0.3.5

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.

Prerequisites

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

Installation

Choose your AI assistant below and follow the instructions.

1. Cursor

One-click install:

Manual setup:

Add to .cursor/mcp.json in your project (or ~/.cursor/mcp.json for global access):

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

2. Claude Code

Run the following command:

claude mcp add gdsfactoryplus -- uvx --from gfp-mcp gfp-mcp-serve

Or add to .claude/settings.json manually:

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

3. 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": "uvx",
            "args": ["--from", "gfp-mcp", "gfp-mcp-serve"]
        }
    }
}

Restart Claude Desktop after adding the configuration.

4. Other MCP Clients

Install gfp-mcp and run the server:

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

Or install globally first, then reference gfp-mcp-serve in your client's MCP configuration:

uv tool install gfp-mcp

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

Tool	Description
list_projects	List all running GDSFactory+ server instances
get_project_info	Get detailed information about a specific project
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
check_drc	Run Design Rule Check verification with structured violation reports
check_connectivity	Run connectivity verification
check_lvs	Run Layout vs. Schematic verification
simulate_component	Run SAX circuit simulations with custom parameters
list_samples	List available sample files from GDSFactory+ General PDK projects
get_sample_file	Get the content of a specific sample file from a project

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