# MCP setup for Claude Code and opencode

This project now uses one canonical launcher:

- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\mcp_wrapper.py`

That wrapper resolves the real server implementation at:

- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\AbletonMCP_AI\AbletonMCP_AI\MCP_Server\server.py`

## Why this exists

The repository currently has mixed historical paths:

- `AbletonMCP_AI/MCP_Server/...`
- `AbletonMCP_AI/AbletonMCP_AI/MCP_Server/...`

Claude Code and opencode were pointing at different locations, and at least one of those locations no longer existed. The wrapper removes that fragility and gives both clients one stable entrypoint.

## Claude Code

Project config lives in:

- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\.mcp.json`

The expected server entry is:

```json
{
  "mcpServers": {
    "ableton-mcp-ai": {
      "type": "stdio",
      "command": "python",
      "args": [
        "C:/ProgramData/Ableton/Live 12 Suite/Resources/MIDI Remote Scripts/mcp_wrapper.py"
      ],
      "env": {
        "PYTHONIOENCODING": "utf-8",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}
```

Notes:

- Claude Code project scope uses `.mcp.json`.
- A local or user server with the same name can override project scope if configured in `~/.claude.json`.
- In this machine, the stale user override was also corrected to use the wrapper.

## opencode

Project config lives in:

- `C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts\opencode.json`

The expected MCP entry is:

```json
{
  "mcp": {
    "ableton-mcp-ai": {
      "type": "local",
      "command": [
        "python",
        "C:/ProgramData/Ableton/Live 12 Suite/Resources/MIDI Remote Scripts/mcp_wrapper.py"
      ],
      "enabled": true,
      "timeout": 20000,
      "environment": {
        "PYTHONIOENCODING": "utf-8",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}
```

The longer timeout matters because the server still initializes and indexes tools even when Ableton is not currently accepting socket connections.

## Manual start

You can start the server manually from the project root with:

```powershell
python .\mcp_wrapper.py --transport stdio
```

Or with the batch helper:

```powershell
.\start_mcp.bat
```

## Verification

Basic MCP protocol verification from Python:

```powershell
@'
import asyncio, os, sys
from pathlib import Path
from mcp.client.stdio import stdio_client, StdioServerParameters
from mcp import ClientSession

root = Path(r"C:\ProgramData\Ableton\Live 12 Suite\Resources\MIDI Remote Scripts")
env = os.environ.copy()
env["PYTHONIOENCODING"] = "utf-8"
env["PYTHONUNBUFFERED"] = "1"

params = StdioServerParameters(
    command=sys.executable,
    args=[str(root / "mcp_wrapper.py")],
    env=env,
)

async def main():
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            print(f"tools={len(tools.tools)}")

asyncio.run(main())
'@ | python -
```

Expected result:

- initialize succeeds
- tool listing succeeds
- the server can load even if Ableton is closed

## Ableton runtime requirement

The MCP server can start without Ableton Live, but tools that talk to the Live remote socket require:

- Ableton Live open
- the matching remote script loaded
- the socket listener available on `127.0.0.1:9877`

If the socket is unavailable, Claude Code or opencode may still connect to MCP successfully, but track and session operations will fail until Ableton is running correctly.

## Known cleanup still pending

- `AbletonMCP_AI\AbletonMCP_AI\MCP_Server\server.py` contains duplicate MCP tool definitions that emit `Tool already exists` warnings on startup.
- Those warnings do not block initialization, but they should be deduplicated in a separate cleanup pass.