---
url: https://chartbuddy.io/hub/docs/connect-mcp.md
---
> Docs index: [llms.txt](https://chartbuddy.io/hub/docs/llms.txt)


# Connect MCP

AI clients talk to **Chartbuddy Hub** through the **Model Context Protocol (MCP)**. Install Hub first: [Windows](https://chartbuddy.io/hub/docs/getting-started/windows.md) or [macOS](https://chartbuddy.io/hub/docs/getting-started/macos.md).

## How clients connect

Clients spawn the Chartbuddy **binary** with `--mcp` over **stdio**. That process talks to Chartbuddy Hub on loopback.

**Framing:** newline-delimited JSON-RPC (preferred) or Content-Length framed MCP. Responses match the request framing.

The MCP server ships inside the Chartbuddy binary. Nothing to `npm install` or launch with `npx`.

On macOS, auto-launch looks for Chartbuddy Hub in this order:

1. `/Applications/Chartbuddy.app/Contents/MacOS/chartbuddy`
2. `~/.local/bin/chartbuddy` (optional symlink, **Help → Install CLI Symlink…**)
3. `chartbuddy` on your `PATH`
4. `open -a Chartbuddy` (Launch Services by name)

## Pick your client

| Client | Guide |
|--------|--------|
| **Cursor** | [Connect Cursor](https://chartbuddy.io/hub/docs/connect-mcp/cursor.md) |
| **Claude (web)** | [Connect Claude (web)](https://chartbuddy.io/hub/docs/connect-mcp/claude.md) |
| **Claude Code** | [Connect Claude Code](https://chartbuddy.io/hub/docs/connect-mcp/claude-code.md) |
| **OpenCode** | [Connect OpenCode](https://chartbuddy.io/hub/docs/connect-mcp/opencode.md) |
| **Google Antigravity** | [Connect Google Antigravity](https://chartbuddy.io/hub/docs/connect-mcp/antigravity.md) |
| **ChatGPT / Codex** | [Connect ChatGPT / Codex](https://chartbuddy.io/hub/docs/connect-mcp/chatgpt-codex.md) |
| **ChatGPT (web)** | [Connect ChatGPT (web)](https://chartbuddy.io/hub/docs/connect-mcp/chatgpt.md) |

## Shared config

Every client uses the same stdio spawn (`args`: `--mcp`):

::: code-group

```json [Windows]
{
  "mcpServers": {
    "Chartbuddy-Hub": {
      "type": "stdio",
      "command": "C:\\Users\\YOUR_USER\\AppData\\Local\\Programs\\Chartbuddy\\chartbuddy.exe",
      "args": ["--mcp"]
    }
  }
}
```

```json [macOS]
{
  "mcpServers": {
    "Chartbuddy-Hub": {
      "type": "stdio",
      "command": "/Applications/Chartbuddy.app/Contents/MacOS/chartbuddy",
      "args": ["--mcp"]
    }
  }
}
```

:::

## Verify

### Status check (read-only)

Fast and synchronous. Never launches Chartbuddy Hub or opens UI:

::: code-group

```powershell [Windows]
& "$env:LOCALAPPDATA\Programs\Chartbuddy\chartbuddy.exe" --mcp-status
```

```bash [macOS]
/Applications/Chartbuddy.app/Contents/MacOS/chartbuddy --mcp-status
```

:::

`--mcp-doctor` is an alias. Exit `0` = Chartbuddy Hub bridge up; `1` = unreachable.

If the port file exists and Chartbuddy Hub windows are visible but status says unreachable, you may be in a **sandbox that denied loopback**. Approve access and re-run.

### Smoke test (optional)

Chartbuddy Hub must be running. Pipe newline JSON-RPC into `--mcp`:

::: code-group

```powershell [Windows]
@"
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_charts","arguments":{}}}
"@ | & "$env:LOCALAPPDATA\Programs\Chartbuddy\chartbuddy.exe" --mcp
```

```bash [macOS]
printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_charts","arguments":{}}}' \
| /Applications/Chartbuddy.app/Contents/MacOS/chartbuddy --mcp
```

:::

| Command | Behavior |
|---------|----------|
| `--mcp-status` / `--mcp-doctor` | Facts + exit; no launch. `--json` / `--setup` optional |
| `chartbuddy --mcp` | Long-lived MCP adapter (stdio); may auto-launch Chartbuddy Hub on first tool call |
| Open Chartbuddy.app | Starts the Chartbuddy Hub GUI |

## Using tools

* **`list_charts`** lists Hub windows (`chart-*`) and CE edit sessions (`ce:*`), each with `surface: tauri|ce`.
* Edits usually target a specific `chart_ref`.
* **`get_active_chart`** returns a real chart window (not menus/popovers).
* Edits happen in Chartbuddy Hub’s desktop windows. Hub has no in-app prompt box.

## Troubleshooting

| Symptom | Check |
|---------|-------|
| MCP tools missing in chat | Config saved? MCP refreshed / new chat? Server enabled for that conversation? |
| Chartbuddy Hub not starting | Launch Chartbuddy Hub; run `chartbuddy --mcp-status` |
| Status “unreachable” but Chartbuddy Hub windows open | Sandbox may have denied loopback. Approve network for `chartbuddy` |
| Permission / Gatekeeper | Open Chartbuddy Hub from its install location the first time |
| Wrong window targeted | Use `list_charts`; ignore popover/menu windows |
| Stale port file | Quit Chartbuddy Hub, delete the Hub `mcp-port` file if needed (macOS / Linux `~/.chartbuddy/mcp-port`, Windows `%USERPROFILE%\.chartbuddy\mcp-port`), relaunch |
| Project MCP config in git | Use user/global scope only |
| Client talking to the Hub `mcp-port` file as MCP | Client must spawn `chartbuddy --mcp` |
| Treating `--mcp-status` as a launcher | Read-only; open the app (or use `--mcp` tool calls) to start Hub |