Blooio MCP Server

Blooio MCP Server

A Model Context Protocol server for the Blooio v4 API. It lets Claude, ChatGPT, Cursor, and any other MCP client send and receive iMessage, SMS, RCS, and WhatsApp messages, and manage channels, numbers, contacts, chats, groups, calls, 10DLC registration, support tickets, webhooks, and the event feed.

It is a thin wrapper: every tool is one Blooio API call, made with the credentials of the person who connected.

Connect

Add this server URL to your MCP client:

https://mcp.blooio.com/v4

The client opens a browser window where you sign in to Blooio, choose the organization to connect, and approve the permissions. Access tokens refresh automatically; you can revoke access any time from your organization's installed apps in the Blooio dashboard.

If your client can't do OAuth, send a Blooio API key instead:

Authorization: Bearer bl_live_...

Tools

There is one tool per v4 API operation, generated from the published OpenAPI spec, so the tool set always matches the docs. Tool arguments are the operation's:

• path parameters, in snake_case (/chats/{chatId} takes chat_id)
• query parameters
• request body fields, flattened to the top level
• idempotencyKey, for operations that accept an Idempotency-Key header

Operations that upload a file (set_group_icon, set_chat_background, upload_contact_card_avatar) take a public URL; the server downloads it and uploads it to Blooio.

When a call fails, the API's error comes back as the tool result, so the model can read it and fix the call.

Resources (blooio://account/info, blooio://channels, blooio://webhooks) and a few starter prompts (send_quick_message, check_delivery, send_with_attachment, verify_contact, setup_webhook, start_group_chat) are also available.

How sign-in works

The server is an OAuth 2.1 authorization server for MCP clients: dynamic client registration, authorization code with PKCE (S256), and refresh tokens. It delegates the actual login to Blooio's OAuth:

1. The MCP client registers at /oauth/register and opens /oauth/authorize.
2. A confirmation page names the client and where it will be redirected, then hands off to Blooio's consent screen as the Blooio MCP app.
3. Blooio redirects back to /oauth/callback. If the app is installed on several of the user's organizations, the server asks which one this connection should use.
4. The client receives Blooio's tokens wrapped with that organization (bmcp_<organization_id>.<token>), so every tool call is pinned to the chosen organization. The server stores no long-lived tokens; refresh requests are forwarded to Blooio.

Discovery documents are served at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource. Calls without valid credentials get 401 with a WWW-Authenticate header pointing at the latter.

Endpoints

Development

Requires Node 22+.

npm install
npm test            # unit tests
npm start           # wrangler dev on http://localhost:8787

To run sign-in locally, create a Blooio app in the dashboard (Developers → Apps) with redirect URI http://localhost:8787/oauth/callback, put its client id in wrangler.toml as BLOOIO_OAUTH_CLIENT_ID, and its secret in .dev.vars:

BLOOIO_OAUTH_CLIENT_SECRET=blosec_...

Then point the MCP Inspector at http://localhost:8787/v4.

Updating the tools

src/operations.json is compiled from the OpenAPI spec. To regenerate it:

npm run sync-spec -- https://docs.blooio.com/openapi.v4.json

License

Apache 2.0