Skip to main content
Glama
README.md
# vibo-mcp

MCP server for [Vibo](https://vibodj.com) (vibodj.com) — plan your event music
as a host/couple. Browse your events and timeline, see and add song requests,
like songs, manage notifications, and export selections to Spotify/Apple Music,
all via natural language.

> Developed and maintained by AI (Claude Code). Use at your own discretion.
> Unofficial — not affiliated with Vibo. Works only with your own account/data.

## Install

```json
{
  "mcpServers": {
    "vibo": {
      "command": "npx",
      "args": ["-y", "vibo-mcp"],
      "env": {
        "VIBO_EMAIL": "you@example.com",
        "VIBO_PASSWORD": "your_password"
      }
    }
  }
}
```

### Authentication

Choose one method:

| Method | Env vars | When |
|--------|----------|------|
| Email + password (recommended) | `VIBO_EMAIL`, `VIBO_PASSWORD` | You sign in to Vibo with an email/password. |
| Captured token | `VIBO_ACCESS_TOKEN` (+ `VIBO_REFRESH_TOKEN`) | Your account uses Apple/Google/Facebook sign-in (no password). Capture `x-token`/`x-refresh-token` from a signed-in `web.vibodj.com` session. |
| Browser capture (SSO) | run `vibo_capture_session` | With the [ContextMint Bridge](#contextmint-bridge-for-sso-capture) browser extension installed and signed into `web.vibodj.com`, capture the token automatically (saved to `~/.vibo-mcp/session.json`). |

The server boots without credentials; the config error only surfaces on the
first tool call.

### ContextMint Bridge (for SSO capture)

`vibo_capture_session` reads your signed-in tab through the ContextMint Bridge
browser extension. Install it from
[github.com/nullnet-app/contextmint-bridge/releases](https://github.com/nullnet-app/contextmint-bridge/releases):

- **Chrome:** download the Chrome zip, unzip it, and load it unpacked at
  `chrome://extensions` (Developer mode → Load unpacked).
- **Safari:** not available yet — it will ship inside the ContextMint app,
  which has no public download. Use Chrome for now.

Approve the pair code the extension shows on first use.

ContextMint Bridge is the fetchproxy browser extension under its new name, from
the same maintainer — fetchproxy's own README
(https://github.com/chrischall/fetchproxy#extension) points to it. Its source is
public at https://github.com/nullnet-app/contextmint-bridge: build it yourself,
or check a release zip against the `.sha256` file published beside it
(`shasum -a 256 -c contextmint-bridge-chrome-<version>.zip.sha256`).

### Uploads

`vibo_set_profile_photo` and photo/file answers to `vibo_answer_question` take
each file one of three ways:

- **A local path** (local installs only). Files are read only from the upload
  directory — `VIBO_UPLOAD_DIR`, default `~/Downloads/vibo-mcp`. Copy a file
  there before asking Claude to upload it. Hidden files and symlinks that lead
  outside the directory are refused. For a photo, the path you pass must be the
  file itself: any symlink is refused, even one pointing inside the upload
  directory. On a hosted deployment a path is refused, with a pointer to the
  routes below.
- **Inline base64** (`fileData`, or `images`/`files`), for small files on any
  deployment. It is decoded strictly: truncated, mis-padded or otherwise
  malformed base64 is refused rather than sent as a corrupt file. A
  `data:<type>;base64,` prefix and line breaks are fine.
- **An upload slot** (hosted deployments with a blob store). Call
  `vibo_upload_slots` with the filenames, `PUT` each file to the signed URL it
  returns (its `curl` field is a ready command), then pass the `blobKey`
  (`blobKey`, or `imageBlobKeys`/`fileBlobKeys`). The stored copy is deleted
  only after Vibo accepts the upload, and the result reports it in
  `blobCleanup`. If the upload fails, the copy is kept so you can retry.

Every route is capped at 25 MiB. Photos must be real images
(jpg/png/gif/webp/heic) by any route: the type must be an image type *and* the
bytes must match it, so a renamed text file is refused. The confirmation preview
shows each file's source, name, type, size and SHA-256. If the bytes change
before you confirm, such as a different file at the same path or a re-uploaded
slot, the confirmation is refused.

### Timeline sections and limits

- `vibo_create_section` adds a section and can place it (`afterSectionId` or a
  0-based `position`). The web app only appends new sections to the end.
  Visibility is `host` (default, "Me and DJ") or `public` (guests too).
- `vibo_delete_section` previews the section's name, its song count and its
  answered questions before deleting. It refuses the DJ's do-not-play list
  (`dontPlay`) and timeline dividers (`headline`) unless you pass `force: true`.
- `vibo_reorder_sections` moves one or more sections to directly after another
  section, or to the start. `vibo_reorder_songs` does the same for songs within
  a section.

Vibo's limits, checked before anything is sent:

| What | Limit |
|---|---|
| Section name | 45 characters (the web app's limit) |
| Song comment (`vibo_update_song`) | 90 characters (an emoji counts as 2) |

A host can only do some things when the DJ's settings allow it: adding or
reordering sections (event settings), or reordering one section's songs (that
section's "hosts can order songs"). Vibo turns "hosts can order songs" **off**
for every section a host creates, and only the DJ can turn it on. When a
setting blocks you, the tool says which one instead of returning Vibo's bare
"Action is not allowed for user".

Vibo doesn't store a section description set by a host, so
`vibo_create_section` takes a note (for the DJ) instead.

### Confirmations

Every write (adding or removing songs, comments, invites, exports, answers,
uploads, …) is confirmed before anything is sent to Vibo.

| variable | default | |
|---|---|---|
| `MCP_CONFIRM_MODE` | `ask-user` | What a write does on a client that cannot show a confirmation prompt (claude.ai, Claude Desktop). `ask-user`: two steps — the first call does nothing and returns a preview plus a token, and the model must get your approval in chat before calling again with it. `auto`: the same two steps, but the model may use the token after reviewing the preview itself. `refuse`: writes are refused on such clients. A client that can show prompts (Claude Code) always gets the real prompt, unless `MCP_CONFIRM_ELICITATION=off`. An unrecognised value is treated as `refuse`. |
| `MCP_CONFIRM_ELICITATION` | `on` | `off` never shows a confirmation prompt, so every client gets the `MCP_CONFIRM_MODE` behaviour. Set it for a client that says it can show prompts but never does (the write hangs — opencode 2.0.x). Any other value is treated as `on`, with a warning on stderr. |
| `MCP_CONFIRM_TTL_SECONDS` | `600` | How long a token stays valid. |
| `MCP_CONFIRM_SECRET` | random per process | Signing key; set it only if tokens must survive a server restart. |

A token works once, only for the tool and arguments it was previewed with: a
changed argument or a reused token is refused and nothing is sent.

## How it works

Vibo's app talks to a GraphQL API at `https://api.vibodj.com/v2/graphql`,
authenticating with an `x-token` header obtained from an email/password
`signIn`. This server reuses that same flow server-side (no browser needed) and
wraps the host/couple operations as MCP tools. Every mutating tool asks you to
confirm first: a client that can show a confirmation prompt (Claude Code) shows
one (unless `MCP_CONFIRM_ELICITATION=off`); otherwise the first call makes no network call and returns a preview plus a
`confirmToken`, and only a repeat call with that token makes the change (see
[Confirmations](#confirmations)).

See [docs/VIBO-API.md](docs/VIBO-API.md) for the reverse-engineered API notes
and [skills/vibo-mcp/SKILL.md](skills/vibo-mcp/SKILL.md) for the full tool list.

## Upgrading

**2.6.0 — upload previews.** In a confirmation preview, `willSend.photo` (`vibo_set_profile_photo`) and each `willSend.uploads[<key>]` (question answers) are now objects, not strings: `{source, path?, blobKey?, filename, mimeType, sizeBytes, sha256}`, where `source` is `path`, `inline` or `blob`. They used to be the path, or the string `"(inline bytes)"`. A caller that displayed the old string should show `filename` (and `path` when present). The `sha256` is what the confirm token is bound to.

## Development

```bash
npm install
npm run build   # tsc + esbuild bundle → dist/
npm test        # vitest
```

## License

MIT

TDQS

A3.6/5.0

Scored across 42 tools

Disambiguation3/5

Most tools target a distinct resource+action, but several pairs genuinely overlap: vibo_update_song can set a comment while vibo_comment_on_song also leaves one, vibo_move_song vs vibo_reorder_songs both reposition songs, and vibo_create_event_contact vs vibo_invite_users both add people to an event. The verbose descriptions usually steer an agent to the right one, but the boundaries require reading rather than being obvious from the names.

Naming Consistency4/5

Nearly every tool follows the vibo_verb_noun pattern (list_events, get_event, create_section, delete_section, reorder_songs, remove_user) with a uniform vibo_ prefix. Minor deviations exist — vibo_healthcheck is a bare noun, vibo_get_notifications_count inverts the order, and exports use a longer verb_phrase_to_target form — but the overall convention is predictable.

Tool Count3/5

42 tools is heavy and beyond the comfortable range, though the domain (events, sections, songs, comments, questions, users, playlists, notifications, auth) is genuinely broad and most tools map to a real operation. Some consolidation is possible — the near-duplicate Spotify and Apple Music export tools could be one parameterized tool, and the four comment create/delete tools could be collapsed.

Completeness3/5

Song, section, comment, question, user and notification lifecycles are covered thoroughly, including reordering, exporting and imports. However, the event lifecycle has notable holes: there is no create_event, update_event or delete_event, and contacts can be created but never updated or deleted — gaps that would block common agent workflows.

Maintenance

ActivityActive
ResponsivenessUsually handled