Sendblue MCP Server

An MCP (Model Context Protocol) server that exposes Sendblue's iMessage and SMS capabilities as tools for LLMs.

Overview

This MCP server acts as an interface to the Sendblue API, enabling LLMs to send messages, manage groups, and perform other communication-related tasks via iMessage and SMS. It follows the MCP specification and provides a standardized way for LLMs to interact with the Sendblue platform.

Features

The server provides the following tools:

send_message: Send individual messages (iMessage/SMS) with support for text, media, and expressive styles
send_group_message: Send messages to group chats
lookup_number_service: Check if a number supports iMessage or SMS
send_typing_indicator: Send typing indicators to recipients
get_message_history: Retrieve message history
add_recipient_to_group: Add new recipients to existing group chats
upload_media_for_sending: Upload media from URLs to Sendblue servers

Quick Start

Fastest Way to Get Started

For Claude Desktop

# Clone the repository
git clone https://github.com/your-username/sendblue-mcp.git
cd sendblue-mcp

# Install dependencies
pip install -r requirements.txt

# Set up credentials
cp sample.env .env
# Edit .env and add your API credentials

# Add to Claude Desktop config (macOS)
echo '{
  "mcpServers": {
    "sendblue": {
      "command": "python",
      "args": ["-m", "src.main"],
      "cwd": "'$(pwd)'"
    }
  }
}' > ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Restart Claude Desktop

For Local Testing

# After cloning and installing dependencies
python start_sendblue.py

Setup

Prerequisites

Python 3.10 or higher
Sendblue API credentials (API Key ID and Secret Key)

Installation

Clone this repository:

git clone https://github.com/your-username/sendblue-mcp.git
cd sendblue-mcp

Install dependencies:
```
pip install -r requirements.txt
```

Configure your Sendblue API credentials:

cp sample.env .env
# Edit .env to add your API credentials

Open .env and add:

SENDBLUE_API_KEY_ID=your_api_key_id_here
SENDBLUE_API_SECRET_KEY=your_api_secret_key_here

Running Locally

Ensure you're in the project directory:
```
cd /path/to/sendblue-mcp
```
Run the server:
```
python -m src.main
```
Or use the convenience script:
```
python start_sendblue.py
```
The server will start using the configuration from your .env file.

Client Integration

Claude Desktop Integration

Claude Desktop allows you to use the Sendblue MCP server directly from the Claude interface:

Locate the Claude Desktop configuration file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %AppData%\Claude\claude_desktop_config.json

Create or edit the file and add the following configuration:

{
   "mcpServers": {
      "sendblue": {
         "command": "python",
         "args": [
            "-m",
            "src.main",
            "--directory",
            "/absolute/path/to/sendblue-mcp"
         ]
      }
   }
}

Replace /absolute/path/to/sendblue-mcp with the actual path to your Sendblue MCP server directory
Save the file and restart Claude Desktop
The Sendblue tools will appear in the Claude interface when you click on the hammer icon

Cursor Integration

To add the Sendblue MCP server to Cursor:

Open Cursor Settings:
- macOS: Press Cmd + ,
- Windows/Linux: Press Ctrl + ,
Navigate to the MCP settings:
- Go to "Features" > "MCP Servers"
Click "Add Server" and configure:
- Server Name: sendblue
- Command: python
- Args: ["-m", "src.main"]
- Working Directory: /absolute/path/to/sendblue-mcp
- Environment Variables:
```
{
  "SENDBLUE_API_KEY_ID": "your_api_key_id",
  "SENDBLUE_API_SECRET_KEY": "your_api_secret_key"
}
```
Save and restart Cursor
Verify the server is connected:
- Open the AI chat
- You should see Sendblue tools available when you click the tools icon
- Try running @sendblue send test message to confirm it's working

Troubleshooting Integration

If the MCP server doesn't appear in Claude Desktop:

Check Claude's logs (macOS): tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
Verify your .env file has valid Sendblue API credentials
Make sure the path in the config file is absolute and correct
Try restarting the client application completely

Deployment

Using Docker

Build and run the Docker container:

docker build -t sendblue-mcp .
docker run -p 5000:5000 --env-file .env sendblue-mcp

Using Smithery

This server is compatible with Smithery hosting. Deploy using:

smithery deploy

API Credentials

Obtaining Sendblue API Keys

Sign up for a Sendblue account at https://sendblue.co/
Once logged in, navigate to the API dashboard
Generate your API Key ID and API Secret Key
Store these credentials securely as they will be needed to authenticate with the Sendblue API

Setting Up Credentials

The server requires two main API credentials:

SENDBLUE_API_KEY_ID: Your Sendblue API Key ID
SENDBLUE_API_SECRET_KEY: Your Sendblue API Secret Key

These can be provided in any of the following ways:

1. Using a .env File (Local Development)

Create a .env file in the root directory with your credentials:

SENDBLUE_API_KEY_ID=your_api_key_id_here
SENDBLUE_API_SECRET_KEY=your_api_secret_key_here
MCP_TRANSPORT=stdio  # or http for web transport

2. For Claude Desktop Integration

When using with Claude Desktop, you can also set these environment variables in your system profile or pass them directly in the Claude Desktop configuration file:

{
   "mcpServers": {
      "sendblue": {
         "command": "python",
         "args": [
            "-m",
            "src.main"
         ],
         "env": {
            "SENDBLUE_API_KEY_ID": "your_api_key_id_here",
            "SENDBLUE_API_SECRET_KEY": "your_api_secret_key_here"
         }
      }
   }
}

3. For Smithery Deployment

When deploying to Smithery, you'll be prompted to input these environment variables through the Smithery interface. The deployment will securely store these values and provide them to your server at runtime.

Configuration

Additional configuration is managed through environment variables:

MCP_TRANSPORT: Transport method (stdio or http); defaults to stdio
MCP_HTTP_PORT: Port number for HTTP transport; defaults to 5000

Testing

The project includes a comprehensive test suite:

python -m unittest discover -s tests

Documentation

API Documentation - Generated documentation for the Sendblue API
Sendblue Documentation - Original Sendblue API documentation

License

This project is licensed under the MIT License - see the LICENSE file for details.

Sendblue