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