Connect Chartbuddy Hub (MCP)

Chartbuddy Hub is the Chartbuddy desktop app. AI clients (Cursor, ChatGPT Desktop, Claude Desktop, Claude Code, …) talk to it through the Model Context Protocol (MCP).

Agents: plaintext first

Prefer /hub/mcp-setup.md or /hub/mcp-setup.json (no JS). On-machine: chartbuddy --mcp-status.

This page is documentation, not the MCP API

There is no MCP endpoint on the docs host, no /hub/openapi.json, and no separate npm MCP package.
Clients must spawn the Chartbuddy binary with --mcp (stdio). Framing: newline-delimited JSON-RPC (preferred) or Content-Length. That process talks to Hub on loopback HTTP. Sandboxed agents may need approval to reach 127.0.0.1.

Machine-specific config — do not commit

Register MCP at user/global scope. Absolute /Applications/... paths must not land in a shared repo (avoid Claude Code project .mcp.json for Chartbuddy).

Cursor in three steps

1. Install Hub to /Applications and launch once (or use Help → Connect Cursor… in Hub).
2. Paste into Cursor MCP settings (~/.cursor/mcp.json — global, not a project file):

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

3. Refresh MCP / restart Cursor and enable ChartBuddy for the chat. Mid-chat attach usually works in Cursor after refresh; open a new agent chat only if tools are still missing. (Claude Code: mid-session attach fails — start a new session.)

Handoff for that new chat:

Chartbuddy MCP is configured (stdio → chartbuddy --mcp → Hub).
Use list_charts for chart-* refs; get_active_chart skips menus/popovers.
If tools are missing, enable the chartbuddy MCP server for this chat.

Read-only status (never launches Hub):

/Applications/Chartbuddy.app/Contents/MacOS/chartbuddy --mcp-status

(--mcp-doctor is the same command.)

How discovery works

AI client (Cursor / Claude / …)
        │  spawns MCP server from its config (stdio)
        ▼
  chartbuddy --mcp   (the Chartbuddy binary in headless adapter mode)
        │  reads ~/.chartbuddy/mcp-port
        │  or launches Chartbuddy Hub if needed
        ▼
  Chartbuddy Hub  (.app) — local HTTP bridge

Layer	What gets discovered	How
AI client → MCP	chartbuddy --mcp process	JSON config (command / args)
MCP → Hub	Running desktop app	Port file ~/.chartbuddy/mcp-port, or auto-launch

The MCP server is built into the Chartbuddy binary — there is no separate Node package to install, and nothing to launch with npx.

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

1. /Applications/Chartbuddy.app/Contents/MacOS/chartbuddy
2. ~/.local/bin/chartbuddy (optional symlink)
3. chartbuddy on your PATH
4. open -a Chartbuddy (Launch Services by name)

So installing Hub into Applications is strongly recommended.

1. Install Chartbuddy Hub (macOS)

1. Open the Chartbuddy .dmg
2. Drag Chartbuddy into Applications
3. Eject the disk image
4. Launch Chartbuddy once from Applications (approve Gatekeeper if prompted)

ls /Applications/Chartbuddy.app/Contents/MacOS/chartbuddy

2. No separate MCP package

Point clients at the app binary with --mcp. Nothing to npm install.

3. Register in your AI client

Release binary: /Applications/Chartbuddy.app/Contents/MacOS/chartbuddy
Dev binary: /ABS/PATH/TO/2_chart_buddy/src-tauri/target/debug/chartbuddy

Cursor

Prefer a single global config with the /Applications path (avoid duplicating global + project entries).

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

Claude Code (CLI) — user scope

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

claude mcp add --transport stdio chartbuddy --scope user -- "/Applications/Chartbuddy.app/Contents/MacOS/chartbuddy" --mcp

Start a new Claude Code session after adding; paste the handoff block above.

Claude Desktop

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

Other MCP hosts

• Command: Chartbuddy binary path
• Args: ["--mcp"]

4. Confirm the connection

1. Hub under /Applications/Chartbuddy.app
2. MCP config saved; client reloaded MCP servers (new chat if needed)
3. Agent can list tools or create a chart
4. Optional:

cat ~/.chartbuddy/mcp-port
/Applications/Chartbuddy.app/Contents/MacOS/chartbuddy --mcp-status

Debug HTTP from the adapter (stderr only — never pollute stdout):

CHARTBUDDY_MCP_DEBUG=1 /Applications/Chartbuddy.app/Contents/MacOS/chartbuddy --mcp

Using tools

• Prefer list_charts to obtain chart-* refs
• get_active_chart skips menus/popovers; open a chart in Hub if none exist

Connection checklist

• [ ] Chartbuddy Hub installed in Applications (macOS)
• [ ] Hub launched at least once
• [ ] AI client MCP config points at the Chartbuddy binary with args: ["--mcp"]
• [ ] Client restarted / MCP servers reloaded / new chat if needed
• [ ] Agent can see Chartbuddy tools

What this is not

• Not the embed package (@chartbuddy.io/embed) — see For LLMs
• Not automatic discovery from Applications by Cursor/Claude — config is required
• Not a cloud MCP endpoint — Hub + MCP talk on localhost
• Not this documentation host acting as an MCP server

Troubleshooting

Symptom	Likely cause	Fix
No Chartbuddy tools in the client	MCP not registered / chat not leased	Fix config; refresh MCP; new chat; enable server for the chat
Tools fail / timeout	Hub not running and not findable	Install to Applications; launch Hub once; run --mcp-status
--mcp-status “hangs” / opens UI	Wrong binary or confused with --mcp	Use a build that prints “read-only — does not launch Hub”; never use --mcp as a health check
Could not locate Chartbuddy app binary	App only in Downloads / build folder	Drag .app to /Applications
Agent edits a menu/popover	Wrong window	Use list_charts; target chart-*
Stale connection	Old port file after crash	Quit Hub, delete ~/.chartbuddy/mcp-port if needed, relaunch

Once connected, agents drive Hub with MCP tools while Hub provides the desktop UI and local bridge.