Blujay

Blujay MCP Server

Let Claude, Cursor, VS Code and other AI assistants work with your Blujay account: read conversations, see who needs a reply, and send iMessage, RCS and SMS from your Blujay phone numbers.

Every text is real. Blujay has no test mode. Most assistants ask before each send unless you've set them to approve tools automatically, so try it with --allow-send-to limited to your own number first (see Safety).

What you can ask

• "Who texted me today that I haven't answered?"
• "Summarize my conversation with Ava and draft a reply."
• "Text +1 555 555 0123: running 10 minutes late."
• "Send Ava the photo on my Desktop called beach.jpg."
• "Text Sam the lease PDF in my Downloads folder."
• "Send Ava happy birthday with balloons."
• "Did my last message to Sam get delivered?"
• "Start the Website demo texts workflow for Ava."
• "Does this number have iMessage?"
• "Set up a webhook to https://example.com/blujay for new messages."
• "How do I verify webhook signatures?"

Setup

You need Node.js 20 or later and a Blujay API key from the API tab in Blujay.

The buttons add the server with a placeholder key; replace blu_your_api_key with yours.

Claude Desktop

Open Settings → Developer → Edit Config and add:

{
  "mcpServers": {
    "blujay": {
      "command": "npx",
      "args": ["-y", "blujay-mcp"],
      "env": { "BLUJAY_API_KEY": "blu_your_api_key" }
    }
  }
}

Restart Claude Desktop.

Claude Code

claude mcp add blujay --env BLUJAY_API_KEY=blu_your_api_key -- npx -y blujay-mcp

Cursor

In Cursor Settings → Tools & MCP → New MCP Server, add to mcp.json:

{
  "mcpServers": {
    "blujay": {
      "command": "npx",
      "args": ["-y", "blujay-mcp"],
      "env": { "BLUJAY_API_KEY": "blu_your_api_key" }
    }
  }
}

VS Code

Add to .vscode/mcp.json in your project:

{
  "servers": {
    "blujay": {
      "command": "npx",
      "args": ["-y", "blujay-mcp"],
      "env": { "BLUJAY_API_KEY": "${input:blujay-api-key}" }
    }
  },
  "inputs": [
    { "id": "blujay-api-key", "type": "promptString", "description": "Blujay API key", "password": true }
  ]
}

Other MCP clients

Run npx -y blujay-mcp with BLUJAY_API_KEY set. It speaks MCP over stdio.

Safety

• Assistants ask before sends. Every tool is labeled read or act, so your client can approve reads and ask before anything reaches a person.
• --allow-send-to +15555550123 limits every send and change to the numbers you list; try it on your own number first.
• --read-only leaves out every tool that sends, changes or deletes.
• Files only by full path: photos, videos, documents, contact cards and audio up to 100 MiB, checked by their contents.

Details, including what these checks can't stop, are in SECURITY.md.

Tools

Tool	What it does	Reaches a person
get_account	Your workspace and phone numbers, and what each can do
list_conversations	Recent conversations, optionally with one person or on one number
get_conversation	A conversation as a transcript, found by phone number, email or chat ID
find_unanswered	Conversations where the other person is waiting on you
get_message	A message's delivery status and why it failed
check_imessage	Whether a number uses iMessage
find_contacts	Search contacts by name, phone or email, or list saved (or unsaved) contacts
list_workflows	Workflows you can start for a contact (active, published, started manually; tag-triggered ones start with save_contact)
list_webhooks	Webhook subscriptions and recent delivery attempts
search_docs	Search docs.blujay.io
send_message	Text a person or group, or reply in a conversation, with an optional photo, video, document, contact card or audio file (sent as a voice memo) from your computer, a photo, video or contact card from a link, or an iMessage effect such as balloons or slam on a follow-up	Yes
react_to_message	Add or remove a tapback or an emoji reaction	Yes
edit_message	Edit a sent iMessage	Yes
unsend_message	Unsend an iMessage	Yes
mark_conversation_read	Mark a conversation as read	Yes (read receipt)
set_typing	Show or hide the typing bubble	Yes
update_group	Rename an iMessage group, or add or remove a person	Yes
save_contact	Create or update a contact, and tag it	Can: a tag can start a workflow that texts them
enroll_in_workflow	Start a manual workflow for a contact; safe to retry, never enrolls twice for the same request	Yes: the workflow texts them
opt_out_contact	Stop all texts to a contact (off with --allow-send-to)
create_webhook	Create a webhook subscription (off with --allow-send-to)
invoke_api	Call any Blujay endpoint (only with --enable-invoke-api)	Depends

Prompts

Your MCP client shows these as ready-made actions:

• Who needs a reply? Finds the conversations waiting on you and drafts a reply for each, without sending.
• Summarize a conversation with one person.
• Send me a test message to your own phone and confirm it arrived.

Options

Option	Effect
--read-only	Only the tools that read
--allow-send-to <numbers>	Only reach these comma-separated numbers
--enable-invoke-api	Add invoke_api for any endpoint. Only GET with --read-only or --allow-send-to
--help, --version

Troubleshooting

• "set BLUJAY_API_KEY": add the key to the env block of your MCP client's config, then restart the client.
• 401, API_KEY_REVOKED or API_KEY_EXPIRED: email [email protected] for a new key, then update BLUJAY_API_KEY.
• The tools don't appear: check that npx -y blujay-mcp --version works in a terminal, and restart your MCP client.

More

• Blujay API docs
• Libraries for your own code: blujay on npm and blujay on PyPI
• Questions and bugs: [email protected] or open an issue. Security issues: SECURITY.md

License

MIT