# GDSFactory+ MCP Server

[![PyPI version](https://img.shields.io/pypi/v/gfp-mcp.svg)](https://pypi.org/project/gfp-mcp/)
[![Python versions](https://img.shields.io/pypi/pyversions/gfp-mcp.svg)](https://pypi.org/project/gfp-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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+](https://gdsfactory.com), 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](https://marketplace.visualstudio.com/items?itemName=gdsfactory.gdsfactoryplus) installed

## Installation

Choose your AI assistant below and follow the instructions.

### 1. Cursor

**One-click install:**

[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=gdsfactoryplus&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLWZyb20iLCJnZnAtbWNwIiwiZ2ZwLW1jcC1zZXJ2ZSJdfQ%3D%3D)

**Manual setup:**

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

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

### 2. Claude Code

Run the following command:

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

Or add to `.claude/settings.json` manually:

```json
{
    "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`

```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:

```bash
uvx --from gfp-mcp gfp-mcp-serve
```

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

```bash
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

<details>
<summary><strong>Server not appearing in Claude</strong></summary>

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

</details>

<details>
<summary><strong>Connection refused errors</strong></summary>

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:

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

</details>

<details>
<summary><strong>Tool execution timeout</strong></summary>

Increase the timeout for long-running operations:

```bash
export GFP_MCP_TIMEOUT=600  # 10 minutes
```

</details>
