---
url: https://chartbuddy.io/hub/docs/getting-started.md
---
# Getting Started

Documentation for **Chartbuddy Hub** — the free desktop app for consultants, analysts, and founders who chart inside AI.

Hub is the Chartbuddy desktop application. It wraps what lives in the Chrome extension into a native desktop experience: waterfalls, mekkos, CAGRs, and the full business chart library, editable on your machine.

## How Hub fits Chartbuddy

| Surface | Role |
|---------|------|
| **Hub** | Desktop editor — prompt from AI, refine locally, push & pull |
| **Embed** | JavaScript package for dashboards, products, and AI chats |
| **Google Slides** | Native editor inside decks, synced to Sheets |
| **PowerPoint** | Coming soon |

Using Embed in your product? See the [Embed docs](https://chartbuddy.io/embed/docs/getting-started/) / [`llms.txt`](https://unpkg.com/@chartbuddy.io/embed/llms.txt) instead.

## Paths

* [Install Hub (macOS)](/getting-started/installation) — download the `.dmg`, Applications, Gatekeeper
* [Connect MCP](/connect-mcp/) — overview, then [Cursor](/connect-mcp/cursor) / [Claude Code](/connect-mcp/claude-code) / [OpenCode](/connect-mcp/opencode) / [ChatGPT / Codex](/connect-mcp/chatgpt-codex) / [ChatGPT](/connect-mcp/chatgpt) / [Claude](/connect-mcp/claude)
* Agent index: [`/hub/llms.txt`](https://chartbuddy.io/hub/llms.txt) → [`mcp-setup.md`](https://chartbuddy.io/hub/mcp-setup.md) → docs `.md` pages
* [Desktop basics](/guides/desktop-basics) — first launch and everyday workflow
* [Push & pull](/guides/push-and-pull) — move charts between Hub and other surfaces

## Also browse

* [Help Center](https://chartbuddy.io/help) — end-user guides for Google Slides
* [Download Hub](https://chartbuddy.io/getstarted#hub) — get the desktop app

---

---
url: https://chartbuddy.io/hub/docs/getting-started/installation.md
---
# Install Hub (macOS)

Chartbuddy Hub is a free desktop application. This page covers the **macOS** install end-to-end — download the `.dmg`, put Hub in Applications, and verify it launches.

Windows builds are coming soon; see the [download page](https://chartbuddy.io/getstarted#hub) for availability.

## 1. Download the macOS installer

Direct download (Apple silicon / arm64 DMG):

**[Download Chartbuddy Hub for macOS](https://chartbuddy.io/downloads/hub/Chartbuddy_macos_aarch64.dmg)**

Or open the [download page](https://chartbuddy.io/getstarted#hub) and click **Download for macOS**.

The file looks like `Chartbuddy_macos_aarch64.dmg` (or a versioned name such as `Chartbuddy_1.7.x_aarch64.dmg`).

## 2. Open the disk image

1. In Finder, open the `.dmg` (usually in **Downloads**)
2. A window appears with the **Chartbuddy** app and an **Applications** shortcut

## 3. Install into Applications

1. Drag **Chartbuddy** into the **Applications** folder
2. Eject the disk image (sidebar or right-click → Eject)
3. You can delete the `.dmg` afterward

Installing into `/Applications` is strongly recommended for MCP and AI clients — the launcher looks there first:

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

## 4. Launch Hub once

1. Open **Chartbuddy** from Applications (or Spotlight: `Chartbuddy`)
2. Approve any macOS prompts
3. Leave Hub running while you use MCP tools, or let the MCP server start it on the first tool call

You should see the Chartbuddy Hub window (desktop chart editor — no prompt box inside the app).

## 5. Connect your AI client (optional)

Hub is operated from Claude, ChatGPT, Cursor, and other MCP clients. After Hub is installed:

1. No separate install — the MCP server is built into the Chartbuddy binary (`chartbuddy --mcp`)
2. In Hub, open **Help → Connect Cursor…** (copies config; can write `~/.cursor/mcp.json`), or follow [Connect Cursor](/connect-mcp/cursor)
3. Refresh MCP in Cursor and open a **new** agent chat

## Verify

| Check | Command / action |
|-------|------------------|
| App present | `ls /Applications/Chartbuddy.app` |
| Binary | `ls /Applications/Chartbuddy.app/Contents/MacOS/chartbuddy` |
| Version | Open Hub → About (or check the window title / docs version) |
| MCP port | After Hub runs, `~/.chartbuddy/mcp-port` should exist |

## Troubleshooting

| Symptom | What to try |
|---------|-------------|
| DMG won't open | Re-download; confirm the file size isn't truncated |
| MCP tools missing | Hub in `/Applications`? Client restarted after MCP config? |
| Hub won't auto-launch | Start Chartbuddy once manually, then retry the MCP tool |

## Next steps

* [Connect MCP](/connect-mcp/) — overview + per-client guides
* [Desktop basics](/guides/desktop-basics) — everyday editing workflow
* [Push & pull](/guides/push-and-pull) — move charts between surfaces

---

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

---

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

Wire **Cursor** to Chartbuddy Hub over local stdio MCP.

::: tip Let Cursor do it
You can paste the following into a Cursor agent chat:

```text
Chartbuddy Hub MCP (Cursor):
1) https://chartbuddy.io/hub/llms.txt
2) https://chartbuddy.io/hub/mcp-setup.md · /hub/mcp-setup.json
3) https://chartbuddy.io/hub/docs/connect-mcp/cursor.md
Typical setup: install Hub if needed, write ~/.cursor/mcp.json (user/global), refresh MCP, confirm with chartbuddy --mcp-status.
```

:::

## Three steps

### 1. Install Chartbuddy Hub

Install Chartbuddy Hub and launch it once before you add the server (approve OS security prompts). On macOS, you can also use **Help → Connect Cursor…** inside Chartbuddy Hub to copy the config.

### 2. Add a custom MCP in Cursor

Open **Cursor Settings → Tools & MCPs**, then under **Home MCP Servers** click **Add Custom MCP**. That opens your user `mcp.json` (on macOS: `~/.cursor/mcp.json`). Prefer this **Home / global** config — do not commit a project-scoped copy.

![Open Tools & MCPs, then Add Custom MCP](/images/cursor-mcp/01-tools-mcps-add-custom.png)

Paste the Chartbuddy server block (toggle OS below), then save the file:

::: 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"]
    }
  }
}
```

:::

![Paste the Chartbuddy config into ~/.cursor/mcp.json](/images/cursor-mcp/02-enter-mcp-json.png)

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

Prefer **one** global config. Duplicate global + project entries make it unclear which server the agent is using.

### 3. Refresh and use

**Refresh MCP** (or restart Cursor) and **enable Chartbuddy for the chat**. Mid-chat attach usually works after a refresh; if tools still do not appear, start a new agent chat.

## Handoff

Optional context for a chat that will use the tools:

```text
Chartbuddy MCP is configured (stdio → chartbuddy --mcp → Chartbuddy Hub).
Transport: newline JSON-RPC or Content-Length framed MCP — not HTTP docs.
Open charts: list_charts — 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.
```

## Verify

::: code-group

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

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

:::

Exit `0` = Chartbuddy Hub bridge up. Keep Chartbuddy Hub running while you chart.

---

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

This page is for **Claude in the browser** (claude.ai) and the **Home** tab in the Claude desktop app. **Claude Code** — including the **Code** tab in the Claude desktop app — uses a different setup. See [Connect Claude Code](/connect-mcp/claude-code).

::: warning Chartbuddy Hub MCP is not available here yet
Chartbuddy Hub connects over **local stdio MCP**. Claude in the browser and the desktop **Home** tab cannot reach a local Chartbuddy Hub process, and we do not ship a **remote MCP** endpoint yet — so regular Claude cannot connect to Chartbuddy Hub MCP today.
:::

## What you can use instead

| Option | Best for |
|--------|----------|
| **[Claude Code](/connect-mcp/claude-code)** | Full Chartbuddy Hub MCP in the terminal or the desktop **Code** tab |
| **[Embed docs](https://chartbuddy.io/embed/docs/getting-started/)** | Charts inside Claude conversations via HTML artifacts and the `@chartbuddy.io/embed` widget |

For Embed, start with [`llms.txt`](https://unpkg.com/@chartbuddy.io/embed/llms.txt), then [Getting started](https://chartbuddy.io/embed/docs/getting-started/) and [Visual QA](https://chartbuddy.io/embed/docs/quality-assurance/visual-qa) in the Embed docs.

---

---
url: https://chartbuddy.io/hub/docs/connect-mcp/claude-code.md
---
# Connect Claude Code

Wire **Claude Code** (CLI) to Chartbuddy Hub over local stdio MCP.

::: info Also covers the Claude Desktop Code tab
These steps apply to **Claude Code** in the terminal and the **Code** tab in the Claude desktop app — that tab is a GUI for Claude Code, not the Home chat tab. For Claude in the browser or the desktop **Home** tab, see [Connect Claude](/connect-mcp/claude).
:::

Use **user** scope so the absolute binary path is not committed to a repo.

::: tip Agent path

1. Fetch [`/hub/llms.txt`](https://chartbuddy.io/hub/llms.txt) → [`mcp-setup.md`](https://chartbuddy.io/hub/mcp-setup.md) → [this page `.md`](https://chartbuddy.io/hub/docs/connect-mcp/claude-code.md).
2. Do not load `llms-full.txt` by default.
   :::

## One-liner

::: code-group

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

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

:::

Equivalent transport form:

::: code-group

```powershell [Windows]
claude mcp add --transport stdio chartbuddy --scope user -- "C:\Users\YOUR_USER\AppData\Local\Programs\Chartbuddy\chartbuddy.exe" --mcp
```

```bash [macOS]
claude mcp add --transport stdio chartbuddy --scope user -- "/Applications/Chartbuddy.app/Contents/MacOS/chartbuddy" --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).
:::

Then start a **new** Claude Code session — mid-session attach fails in Claude Code.

## Handoff

Optional context for a chat that will use the tools:

```text
Chartbuddy MCP is configured (stdio → chartbuddy --mcp → Chartbuddy Hub).
Transport: newline JSON-RPC or Content-Length framed MCP — not HTTP docs.
Open charts: list_charts (chart-* refs). get_active_chart skips menus/popovers.
Missing tools usually mean the chartbuddy MCP server is off for the chat, or a new chat is needed.
```

## Verify

::: code-group

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

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

:::

Keep Chartbuddy Hub running while you chart.

---

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

Wire **[OpenCode](https://opencode.ai)** to Chartbuddy Hub over local stdio MCP.

OpenCode config uses a top-level `mcp` key (not `mcpServers`). Local servers are `type: "local"` with the binary and args in one `command` array.

Prefer the **global** config so the absolute Chartbuddy path is not committed to a repo:

* Global: `~/.config/opencode/opencode.json` (or `.jsonc`)
* Project: `opencode.json` / `opencode.jsonc` in the repo root (avoid for Chartbuddy Hub — machine-specific path)

::: tip Agent path

1. Fetch [`/hub/llms.txt`](https://chartbuddy.io/hub/llms.txt) → [`mcp-setup.md`](https://chartbuddy.io/hub/mcp-setup.md) → [this page `.md`](https://chartbuddy.io/hub/docs/connect-mcp/opencode.md).
2. Do not load `llms-full.txt` by default.
   :::

## Config

Add a `chartbuddy` entry under `mcp`:

::: code-group

```json [Windows]
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "chartbuddy": {
      "type": "local",
      "command": [
        "C:\\Users\\YOUR_USER\\AppData\\Local\\Programs\\Chartbuddy\\chartbuddy.exe",
        "--mcp"
      ],
      "enabled": true
    }
  }
}
```

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

:::

::: 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).
:::

Keep **Chartbuddy Hub** running, restart OpenCode (or reload config), and start a new session if tools do not appear.

## Verify

::: code-group

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

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

:::

Exit `0` = Chartbuddy Hub bridge up.

## Handoff

Optional context for a chat that will use the tools:

```text
Chartbuddy MCP is configured (stdio → chartbuddy --mcp → Chartbuddy Hub).
Transport: newline JSON-RPC or Content-Length framed MCP — not HTTP docs.
Open charts: list_charts (chart-* refs). get_active_chart skips menus/popovers.
Missing tools usually mean the chartbuddy MCP server is off for the chat, or a new chat is needed.
```

---

---
url: https://chartbuddy.io/hub/docs/connect-mcp/chatgpt-codex.md
---
# Connect ChatGPT / Codex

This page is for **Codex CLI** and the **Codex** tab in the ChatGPT desktop application. **ChatGPT** in the browser and regular chat in the desktop app use a different path. See [Connect ChatGPT](/connect-mcp/chatgpt).

Install Chartbuddy Hub and launch it once before you add the server.

::: tip Agent path

1. Fetch [`/hub/llms.txt`](https://chartbuddy.io/hub/llms.txt) → [`mcp-setup.md`](https://chartbuddy.io/hub/mcp-setup.md) → [this page `.md`](https://chartbuddy.io/hub/docs/connect-mcp/chatgpt-codex.md).
2. Do not load `llms-full.txt` by default.
   :::

## 1. Open Settings

In the ChatGPT desktop app, click **Settings** in the **bottom-left** corner of the sidebar.

![Click Settings in the bottom-left of ChatGPT Desktop](/images/chatgpt-mcp/01-click-settings.png)

## 2. Plugins → MCPs

In the settings sidebar, open **Plugins** (under Integrations). Then open the **MCPs** tab.

![Open Plugins, then the MCPs tab](/images/chatgpt-mcp/02-plugins-then-mcps.png)

## 3. Add server

On the MCPs tab, click **+ Add server**.

![Click Add server on the MCPs tab](/images/chatgpt-mcp/03-add-server.png)

## 4. Enter the Chartbuddy details

Choose **Connect to a custom MCP** (STDIO). Fields appear in this order — fill in every row:

| Field | Value |
|-------|--------|
| **Name** | `chartbuddy` (or `chartbuddy-mcp`) |
| **Type** | **STDIO** |
| **Command to launch** | `/Applications/Chartbuddy.app/Contents/MacOS/chartbuddy` |
| **Arguments** | `--mcp` |
| **Environment variables** | leave empty |
| **Working directory** | leave the default |

::: info Windows command
`C:\Users\YOUR_USER\AppData\Local\Programs\Chartbuddy\chartbuddy.exe` — use this for **Command to launch** on Windows. A public Windows Chartbuddy Hub build is not shipping yet; use the macOS path until it does, then replace `YOUR_USER` (or use the path shown after install).
:::

Click **Save**.

![Enter Chartbuddy STDIO command and --mcp argument](/images/chatgpt-mcp/04-enter-details.png)

## After saving

1. Keep **Chartbuddy Hub** running.
2. Start a **new** Codex session and enable the Chartbuddy MCP server for that session if tools do not appear.
3. If ChatGPT asks to approve **network / loopback** for `chartbuddy`, approve it — the adapter must reach Chartbuddy Hub on `127.0.0.1`.
4. Optional check:

::: code-group

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

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

:::

Exit `0` = Chartbuddy Hub is up.

## Handoff

Optional context for a chat that will use the tools:

```text
Chartbuddy MCP is configured (stdio → chartbuddy --mcp → Chartbuddy Hub).
Transport: newline JSON-RPC or Content-Length framed MCP — not HTTP docs.
Open charts: list_charts (chart-* refs). get_active_chart skips menus/popovers.
Missing tools usually mean the chartbuddy MCP server is off for the chat, or a new chat is needed.
```

## Troubleshooting

### Tool call blocked — “reasoning summaries” / organization verification

On the desktop **Codex** tab, Chartbuddy may be configured correctly and still fail when OpenAI’s automatic approval reviewer blocks the tool call — often with an error about **“reasoning summaries”** requiring organization verification. That comes from OpenAI’s approval / org settings, **not** from Chartbuddy or a bad MCP path.

**Options:**

1. Use **Codex CLI** instead of the desktop Codex tab (same MCP config, often fewer approval blockers), or
2. Verify your organization at [platform.openai.com/settings/organization/general](https://platform.openai.com/settings/organization/general), **or** switch to another editor — we recommend [Cursor](/connect-mcp/cursor), [Claude Code](/connect-mcp/claude-code), or [OpenCode](/connect-mcp/opencode).

---

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

This page is for **ChatGPT in the browser** (chatgpt.com) and regular chat in the ChatGPT desktop app. **Codex** — including **Codex CLI** and the **Codex** tab in the ChatGPT desktop application — uses a different setup. See [Connect ChatGPT / Codex](/connect-mcp/chatgpt-codex).

::: warning Chartbuddy Hub MCP is not available here yet
Chartbuddy Hub connects over **local stdio MCP**. ChatGPT in the browser and regular desktop chat cannot reach a local Chartbuddy Hub process, and we do not ship a **remote MCP** endpoint yet — so regular ChatGPT cannot connect to Chartbuddy Hub MCP today.
:::

## What you can use instead

| Option | Best for |
|--------|----------|
| **[ChatGPT / Codex](/connect-mcp/chatgpt-codex)** | Full Chartbuddy Hub MCP in Codex CLI or the desktop **Codex** tab |
| **[Embed docs](https://chartbuddy.io/embed/docs/getting-started/)** | Charts inside ChatGPT conversations via HTML artifacts and the `@chartbuddy.io/embed` widget |

For Embed, start with [`llms.txt`](https://unpkg.com/@chartbuddy.io/embed/llms.txt), then [Getting started](https://chartbuddy.io/embed/docs/getting-started/) and [Visual QA](https://chartbuddy.io/embed/docs/quality-assurance/visual-qa) in the Embed docs.

---

---
url: https://chartbuddy.io/hub/docs/guides.md
---
# Guides

Workflow guides for Chartbuddy Hub — the desktop editor for AI-driven charting.

## Topics

* [Desktop basics](/guides/desktop-basics) — first launch, editing, and exporting
* [Push & pull](/guides/push-and-pull) — move charts between Hub and other surfaces
* [From Chrome extension](/guides/from-chrome-extension) — what carries over from the Slides extension

## Related docs

* [Embed docs](https://chartbuddy.io/embed/docs/getting-started/) — JavaScript package for dashboards and products
* [Help Center](https://chartbuddy.io/help) — Google Slides end-user guides

---

---
url: https://chartbuddy.io/hub/docs/guides/desktop-basics.md
---
# Desktop basics

Chartbuddy Hub is your local chart editor. You operate it from your AI chat — Hub itself has no prompt box. MCP is the remote control; Hub is where charts live and get edited.

## First launch

1. Install Hub to **Applications** from the `.dmg`
2. Open Chartbuddy once (approve Gatekeeper if asked)
3. Confirm the bridge is up: `cat ~/.chartbuddy/mcp-port` prints a port
4. Connect your AI client — see [Connect MCP](/connect-mcp/) (or **Help → Connect Cursor…** in Hub)

Leave Hub installed under `/Applications` so MCP auto-launch can find it.

## Typical workflow

1. **Prompt in AI** — ask Cursor, Claude, ChatGPT, or another MCP-connected client to create or update a chart
2. **Refine in Hub** — focus the chart window for pixel-level control (toolbar, spreadsheet panel, context menus)
3. **Push out** — send the live chart to Google Slides, Notion, Slack, or export as PNG
4. **Pull back** — grab a Chartbuddy PNG from another surface and pull it into Hub to edit again

## What Hub shares with the Chrome extension

Hub packs the same chart engine as the Chartbuddy Google Slides extension:

* Waterfalls, mekkos, stacked bars, CAGRs, and the full business library
* Native editing — not a static screenshot
* Brand styling and number formats

The desktop shell adds push/pull, MCP integration, and a standalone window without a browser tab.

## Next

* [Connect MCP](/connect-mcp/) — Cursor, ChatGPT, Claude, …
* [Push & pull](/guides/push-and-pull) — moving charts between surfaces

---

---
url: https://chartbuddy.io/hub/docs/guides/push-and-pull.md
---
# Push & pull

Hub is the bridge between AI-generated charts and the surfaces where you deliver work.

## Push

**Push** sends a live Chartbuddy chart out of Hub to another surface:

* Google Slides (native editor)
* Notion, Slack, email (as Chartbuddy PNG)
* Other destinations (expanding)

Charts stay alive where the destination supports native Chartbuddy editing (Slides today; PowerPoint soon).

## Pull

**Pull** brings a Chartbuddy chart back into Hub so you can edit it again:

1. Find a Chartbuddy PNG or chart artifact on another surface
2. Click and hold, drag to Hub, release
3. The chart becomes editable in the desktop app

Surfaces with a native Chartbuddy editor (Google Slides, PowerPoint) do not need pull-back — you edit there directly.

## When to use Hub vs Slides

| Scenario | Surface |
|----------|---------|
| Prompting from AI, quick iteration | Hub |
| Final deck in Google Workspace | Google Slides extension |
| Chart arrived as PNG in Slack/Notion | Pull into Hub |

::: info Placeholder
Step-by-step push/pull animations and supported MIME types will be documented here.
:::

---

---
url: https://chartbuddy.io/hub/docs/guides/from-chrome-extension.md
---
# From Chrome extension

Chartbuddy Hub is the desktop packaging of what already exists in the **Google Slides Chrome extension**.

## Shared engine

Both surfaces run the same charting core:

* Chart types: waterfall, mekko, stacked bar, line, stacked area, pie, scatter, combo, …
* Data model and styling defaults
* Native in-place editing

Hub does not replace the Slides extension — it complements it for AI-first workflows and desktop push/pull.

Agents can also drive the extension as a **chart head** of Hub over MCP (`surface: "ce"`, refs `ce:*`): Hub stays the single MCP entry; CE renders and edits in Slides. Internal vision + decisions: [`docs/ce-as-hub-head.md`](../../docs/ce-as-hub-head.md).

## What's different in Hub

| Chrome extension | Hub desktop |
|------------------|-------------|
| Lives inside Google Slides | Standalone desktop app |
| Sheets sync for deck data | MCP bridge for AI clients |
| OAuth to Google (in-browser tab) | System browser + localhost callback (PKCE) |
| SSO (WorkOS, work-email form) | Same WorkOS path; loopback + PKCE token exchange |
| Google account required | Email/password sign-in for users without Google or org SSO |
| Deck-native editing | Push/pull to multiple surfaces |

## Migration mental model

If you already use Chartbuddy in Slides, think of Hub as:

* The place AI agents send charts before they land in a deck
* The editor for charts that arrive as PNGs from chat or other tools
* The same chart quality, without opening a presentation

::: info Placeholder
Parity matrix (feature-by-feature) and shared keyboard shortcuts will be added as Hub ships.
:::