> Docs index: [llms.txt](https://chartbuddy.io/hub/docs/llms.txt)

# Chartbuddy Hub – MCP setup

**This URL is documentation / a connect descriptor – not an MCP endpoint.**  
There is no MCP server on this host and no `/hub/openapi.json`.  
Clients connect by spawning the Chartbuddy **binary** with `--mcp` (stdio).

```
X-ChartBuddy-Resource: docs / agent-setup
X-ChartBuddy-MCP-Transport: stdio
```

Machine-readable twin: `/hub/mcp-setup.json` · Index: `/hub/llms.txt` (also `/hub/docs/llms.txt`)  
Human docs (HTML): `/hub/docs/connect-mcp/` · Markdown twins: `/hub/docs/connect-mcp/*.md`  
Per client `.md` (recommended first): `…/cursor.md` · `…/claude-code.md` · `…/opencode.md` · `…/antigravity.md` · `…/chatgpt-codex.md` · `…/chatgpt.md` (web) · `…/claude.md` (web)

## Quickstart

| Field | Value |
|-------|--------|
| Transport | **stdio** (not HTTP) |
| Framing | **Newline-delimited JSON-RPC** (preferred) **or** Content-Length framed MCP |
| Command (macOS) | `/Applications/Chartbuddy.app/Contents/MacOS/chartbuddy` |
| Command (Windows) | `%LOCALAPPDATA%\Programs\Chartbuddy\chartbuddy.exe` |
| Args | `--mcp` |
| Status | `<chartbuddy binary> --mcp-status` (read-only; never launches Hub) |

## Cursor – user/global `mcp.json` (do not commit) – recommended

Hub's AI connections button writes the same shape (`Chartbuddy-Hub`). Legacy key `chartbuddy` still works until migrated. Config path: macOS / Linux `~/.cursor/mcp.json`, Windows `%USERPROFILE%\.cursor\mcp.json`.

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

On Windows, set `command` to `%LOCALAPPDATA%\Programs\Chartbuddy\chartbuddy.exe` (expanded absolute path).

## Claude Code (user scope) – recommended

Also applies to the **Code** tab in the Claude desktop app (GUI for Claude Code).

```bash
# macOS
claude mcp add-json chartbuddy '{"type":"stdio","command":"/Applications/Chartbuddy.app/Contents/MacOS/chartbuddy","args":["--mcp"]}' --scope user

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

## OpenCode (global) – recommended

Global OpenCode config (`opencode.json` or `.jsonc`): macOS / Linux `~/.config/opencode/`, Windows `%USERPROFILE%\.config\opencode\`. Servers live under `mcp.servers`. `command` is one array (binary + args). Hub's AI connections button writes `Chartbuddy-Hub`:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "Chartbuddy-Hub": {
        "type": "local",
        "command": ["/Applications/Chartbuddy.app/Contents/MacOS/chartbuddy", "--mcp"]
      }
    }
  }
}
```

On Windows, use the Windows Chartbuddy `.exe` path as the first `command` array entry.

## Google Antigravity

Global MCP file: macOS / Linux `~/.gemini/config/mcp_config.json`, Windows `%USERPROFILE%\.gemini\config\mcp_config.json`. Hub's AI connections button writes the same shape:

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

On Windows, set `command` to the Windows Chartbuddy `.exe` path. Restart Antigravity or start a new conversation after saving.

## Claude (web) – browser / desktop Home tab

Hub MCP is **not** available here yet – no remote MCP endpoint. Use [Claude Code](#claude-code-user-scope) for Hub MCP, or the [Embed docs](https://chartbuddy.io/embed/docs/getting-started.md) for charts in regular Claude chats.

## ChatGPT / Codex

For **Codex CLI** and the **Codex** tab in the ChatGPT desktop app:

1. **Settings** (bottom-left) → **Plugins** → **MCPs** tab → **+ Add server**
2. Type **STDIO**
3. Command: macOS `/Applications/Chartbuddy.app/Contents/MacOS/chartbuddy` · Windows `%LOCALAPPDATA%\Programs\Chartbuddy\chartbuddy.exe`
4. Arguments: `--mcp`
5. Save → keep Hub running → **new session**; approve loopback/network if prompted

Illustrated steps: `/hub/docs/connect-mcp/chatgpt-codex`

Desktop Codex tab may block tool calls with an OpenAI approval / “reasoning summaries” organization-verification error even when MCP is correct. Workarounds: Codex CLI, verify org at https://platform.openai.com/settings/organization/general, or use Cursor / Claude Code / OpenCode.

## ChatGPT (web) – browser / regular desktop chat

Hub MCP is **not** available here yet – no remote MCP endpoint. Use [ChatGPT / Codex](#chatgpt--codex) for Hub MCP, or the [Embed docs](https://chartbuddy.io/embed/docs/getting-started.md) for charts in regular ChatGPT chats.

## Status check (read-only – never launches Hub)

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

# Windows
"%LOCALAPPDATA%\Programs\Chartbuddy\chartbuddy.exe" --mcp-status
```

Exit `0` = Hub bridge up; `1` = unreachable. Alias: `--mcp-doctor`.  
Facts + exit code only. `--json` for the same fields as an object. `--setup` adds mcp.json + docs URLs.

## Hub must be running for a live bridge

```bash
# macOS
open -a Chartbuddy
/Applications/Chartbuddy.app/Contents/MacOS/chartbuddy --mcp-status

# Windows: launch Chartbuddy from Start / installed shortcut, then:
"%LOCALAPPDATA%\Programs\Chartbuddy\chartbuddy.exe" --mcp-status
```

## Smoke test (newline JSON-RPC; Hub must be running)

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

On Windows, pipe the same three JSON lines into `"%LOCALAPPDATA%\Programs\Chartbuddy\chartbuddy.exe" --mcp`.

Sample `tools/call` body:

```json
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_charts","arguments":{}}}
```

## After configuring a client

1. Refresh MCP / restart the client.
2. **Claude Code / Codex:** new session if tools are missing. **Cursor:** mid-chat attach usually works after refresh.