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

1. Clone this repository:

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

2. Install dependencies:

   pip install -r requirements.txt
   

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

1. Ensure you're in the project directory:

   cd /path/to/sendblue-mcp
   

2. 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:

1. Locate the Claude Desktop configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %AppData%\Claude\claude_desktop_config.json

2. Create or edit the file and add the following configuration:

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

3. Replace /absolute/path/to/sendblue-mcp with the actual path to your Sendblue MCP server directory

4. Save the file and restart Claude Desktop

5. 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:

1. Open Cursor Settings:

   • macOS: Press Cmd + ,
   • Windows/Linux: Press Ctrl + ,

2. Navigate to the MCP settings:

   • Go to "Features" > "MCP Servers"

3. 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"
     }
     

4. Save and restart Cursor

5. 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:

1. Check Claude's logs (macOS): tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
2. Verify your .env file has valid Sendblue API credentials
3. Make sure the path in the config file is absolute and correct
4. 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

1. Sign up for a Sendblue account at https://sendblue.co/
2. Once logged in, navigate to the API dashboard
3. Generate your API Key ID and API Secret Key
4. 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.