---
url: https://chartbuddy.io/hub/docs/connect-mcp.md
---
# Connect MCP

AI clients talk to **Chartbuddy Hub** through the **Model Context Protocol (MCP)**. Install Hub first: [Install Chartbuddy Hub](/getting-started/installation).

::: tip Agent-readable setup

* This docs host is not an MCP server: there is no `/hub/openapi.json`, and JSON-RPC POSTs here are not MCP.
* **Fetch** [`/hub/llms.txt`](https://chartbuddy.io/hub/llms.txt) (curated index), then [`mcp-setup.md`](https://chartbuddy.io/hub/mcp-setup.md) / [`.json`](https://chartbuddy.io/hub/mcp-setup.json) and the client page `.md` you need — do **not** load `llms-full.txt` by default.
* `curl` of this HTML path redirects common agent user-agents to `/hub/mcp-setup.md`.
* Humans should use the client guides below.
  :::

## Shared handoff

Paste into a new agent chat when wiring Hub MCP:

```text
Chartbuddy Hub MCP (stdio → chartbuddy --mcp → Hub). Docs host is not an MCP endpoint.
1) Fetch https://chartbuddy.io/hub/llms.txt (index)
2) Fetch https://chartbuddy.io/hub/mcp-setup.md (+ .json when configuring a client)
3) Fetch linked /hub/docs/.../*.md pages you need — do not load llms-full.txt by default
Prefer user/global MCP config. Confirm with chartbuddy --mcp-status (read-only).
```

## 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](/connect-mcp/cursor) |
| **Claude** | [Connect Claude](/connect-mcp/claude) |
| **Claude Code** | [Connect Claude Code](/connect-mcp/claude-code) |
| **OpenCode** | [Connect OpenCode](/connect-mcp/opencode) |
| **ChatGPT / Codex** | [Connect ChatGPT / Codex](/connect-mcp/chatgpt-codex) |
| **ChatGPT** | [Connect ChatGPT](/connect-mcp/chatgpt) |

## Shared config

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

::: code-group

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

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

:::

::: info Windows install
A public Windows Chartbuddy Hub build is not shipping yet. Use the **macOS** tab until it does, then replace `YOUR_USER` (or use the path shown after install).
:::

## 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` | One-shot print + exit; no launch |
| `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.

Optional handoff for a chat that will use the tools:

```text
Chartbuddy MCP is configured (stdio → chartbuddy --mcp → Chartbuddy Hub).
Open charts: list_charts lists Hub chart-* and CE ce:* (surface tauri|ce). get_active_chart prefers a focused CE session when the extension bridge is connected.
Missing tools usually mean the chartbuddy MCP server is off for the chat, or a new chat is needed.
```

## 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 from Applications; 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 Applications the first time |
| Wrong window targeted | Use `list_charts`; ignore popover/menu windows |
| Stale port file | Quit Chartbuddy Hub, delete `~/.chartbuddy/mcp-port` if needed, relaunch |
| Project MCP config in git | Use user/global scope only |
| Client talking to `~/.chartbuddy/mcp-port` 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 |