# coda-mcp

MCP server for quantum computing tools. Provides circuit simulation, transpilation, QPU access, and research paper search.

Works with MCP-compatible clients that support stdio transport: Claude Desktop, Claude Code (CLI), VS Code, Cursor, Zed, and more.

## Quick Start

### 1. Get your API token

Generate a token at [coda.conductorquantum.com/settings/api](https://coda.conductorquantum.com/settings/api)

### 2. Configure your MCP client

<details>
<summary><b>Claude Desktop</b></summary>

Add to your Claude Desktop config:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%AppData%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "coda": {
      "command": "/path/to/uvx",
      "args": ["coda-mcp"],
      "env": {
        "CODA_API_TOKEN": "your-token-here"
      }
    }
  }
}
```

Find your uvx path with `which uvx` (typically `~/.local/bin/uvx` or `/usr/local/bin/uvx`).

Restart Claude Desktop after saving.
</details>

<details>
<summary><b>Claude Code (CLI)</b></summary>

**Quick install via CLI:**
```bash
claude mcp add --env CODA_API_TOKEN=your-token-here coda -- uvx coda-mcp
```

**Or manual configuration** - add to `~/.claude.json`:

```json
{
  "mcpServers": {
    "coda": {
      "command": "/path/to/uvx",
      "args": ["coda-mcp"],
      "env": {
        "CODA_API_TOKEN": "your-token-here"
      }
    }
  }
}
```

**Team-shared config** - add `.mcp.json` to your project root:

```json
{
  "mcpServers": {
    "coda": {
      "command": "/path/to/uvx",
      "args": ["coda-mcp"],
      "env": {
        "CODA_API_TOKEN": "${CODA_API_TOKEN}"
      }
    }
  }
}
```

Then team members only need to set `CODA_API_TOKEN` in their environment.
</details>

<details>
<summary><b>Cursor</b></summary>

Add to your Cursor MCP config (`~/.cursor/mcp.json` or `.cursor/mcp.json` in project root):

```json
{
  "mcpServers": {
    "coda": {
      "command": "/path/to/uvx",
      "args": ["coda-mcp"],
      "env": {
        "CODA_API_TOKEN": "your-token-here"
      }
    }
  }
}
```

Find your uvx path with `which uvx`.
</details>

<details>
<summary><b>Zed</b></summary>

Add to your Zed settings (`~/.config/zed/settings.json`):

```json
{
  "context_servers": {
    "coda": {
      "command": {
        "path": "/path/to/uvx",
        "args": ["coda-mcp"],
        "env": {
          "CODA_API_TOKEN": "your-token-here"
        }
      }
    }
  }
}
```
</details>

<details>
<summary><b>Generic MCP Client</b></summary>

For any MCP-compatible client, configure:

- **Transport:** stdio
- **Command:** `uvx coda-mcp`
- **Environment:** `CODA_API_TOKEN=your-token-here`

Or if you prefer pip installation:
```bash
pip install coda-mcp
coda-mcp  # runs the server
```
</details>

## Installation

```bash
# Using uvx (recommended, no install needed)
uvx coda-mcp

# Using pip
pip install coda-mcp

# Using uv
uv tool install coda-mcp
```

## Tools

### Quantum Circuit Tools

| Tool | Description |
|------|-------------|
| `transpile` | Convert between quantum frameworks (Qiskit, Cirq, PennyLane, Braket, PyQuil, CUDA-Q, OpenQASM) |
| `simulate` | Run circuit simulation (CPU via Aer, GPU via CUDA-Q) |
| `to_openqasm3` | Convert circuit to OpenQASM 3.0 |
| `estimate_resources` | Analyze qubit count, depth, and gate counts |
| `split_circuit` | Cut large circuits for distributed execution |

### QPU Tools

| Tool | Description |
|------|-------------|
| `qpu_submit` | Submit circuit to QPU backend (IonQ, IQM, Rigetti, AQT) |
| `qpu_status` | Check job status and get results |
| `qpu_devices` | List available QPU devices |

### Search Tools

| Tool | Description |
|------|-------------|
| `search_papers` | Search quantum computing papers via Exa |
| `get_paper` | Fetch full paper contents |

## Examples

### Simulate a Bell State

```
Create and simulate a Bell state circuit
```

The `simulate` tool accepts Qiskit code:

```python
from qiskit import QuantumCircuit
qc = QuantumCircuit(2)
qc.h(0)
qc.cx(0, 1)
qc.measure_all()
```

### Submit to Real QPU

```
Convert my circuit to OpenQASM and submit to IonQ
```

1. Use `to_openqasm3` to convert your circuit
2. Use `qpu_submit` with `backend="ionq"` to submit
3. Use `qpu_status` to check results

## Environment Variables

| Variable | Description | Required |
|----------|-------------|----------|
| `CODA_API_TOKEN` | Your API token from [coda.conductorquantum.com/settings/api](https://coda.conductorquantum.com/settings/api) | Yes |
| `CODA_API_URL` | API endpoint URL (default: production API) | No |


## Troubleshooting

**"CODA_API_TOKEN not set"**
- Ensure the environment variable is set in your MCP client config
- Verify your token is valid at [coda.conductorquantum.com/settings/api](https://coda.conductorquantum.com/settings/api)

**"Connection refused"**
- Check your internet connection
- The Coda API may be temporarily unavailable

**Tools not appearing**
- Restart your MCP client after configuration changes
- Verify `uvx coda-mcp` runs without errors in terminal
- Check that JSON config syntax is valid

**Debug logs (Claude Desktop)**
- macOS: `~/Library/Logs/Claude/mcp.log` and `mcp-server-coda.log`
- Windows: `%AppData%\Claude\logs\`

**Debug logs (Claude Code)**
```bash
claude mcp list        # Check server status
/mcp                   # Check status in Claude Code session
```

**Windows-specific issues**
- If `uvx` is not found, use full path or install via `pip install coda-mcp`
- Add `APPDATA` to env if you see ENOENT errors

## License

MIT
