Model Context Protocol (MCP)

The Sendblue MCP server lets AI assistants interact with the Sendblue API — send messages, manage contacts, look up numbers, and more — directly from your editor or agent framework.

Quick Start

Install the MCP server via npx:

export SENDBLUE_API_API_KEY="your-api-key"
export SENDBLUE_API_API_SECRET="your-api-secret"
npx -y sendblue-api-mcp@latest

You can find your API credentials in the Sendblue dashboard.

Setup by Client

Claude Desktop

Add the following to your Claude Desktop config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "sendblue_api": {
      "command": "npx",
      "args": ["-y", "sendblue-api-mcp", "--client=claude", "--tools=all"],
      "env": {
        "SENDBLUE_API_API_KEY": "your-api-key",
        "SENDBLUE_API_API_SECRET": "your-api-secret"
      }
    }
  }
}

Claude Code

claude mcp add sendblue_api \
  --env SENDBLUE_API_API_KEY=your-api-key \
  --env SENDBLUE_API_API_SECRET=your-api-secret \
  -- npx -y sendblue-api-mcp --client=claude-code --tools=all

Cursor

Add to your Cursor MCP config (.cursor/mcp.json in your project or ~/.cursor/mcp.json globally):

{
  "mcpServers": {
    "sendblue_api": {
      "command": "npx",
      "args": ["-y", "sendblue-api-mcp", "--client=cursor", "--tools=all"],
      "env": {
        "SENDBLUE_API_API_KEY": "your-api-key",
        "SENDBLUE_API_API_SECRET": "your-api-secret"
      }
    }
  }
}

VS Code

Add to your VS Code user settings (settings.json):

{
  "mcp": {
    "servers": {
      "sendblue_api": {
        "command": "npx",
        "args": ["-y", "sendblue-api-mcp", "--tools=all"],
        "env": {
          "SENDBLUE_API_API_KEY": "your-api-key",
          "SENDBLUE_API_API_SECRET": "your-api-secret"
        }
      }
    }
  }
}

Other MCP Clients

For any MCP client that supports JSON configuration, use the following pattern:

{
  "mcpServers": {
    "sendblue_api": {
      "command": "npx",
      "args": ["-y", "sendblue-api-mcp", "--tools=all"],
      "env": {
        "SENDBLUE_API_API_KEY": "your-api-key",
        "SENDBLUE_API_API_SECRET": "your-api-secret"
      }
    }
  }
}

Filtering Tools

By default, --tools=all exposes every endpoint. For large context windows or specific use cases, you can filter what’s available:

# Only read operations (get/list)
npx -y sendblue-api-mcp --operation=read

# Only message-related tools
npx -y sendblue-api-mcp --resource=messages

# Exclude specific tools
npx -y sendblue-api-mcp --resource=messages --no-tool=send_messages

# Combine filters
npx -y sendblue-api-mcp --resource=messages,contacts --operation=read

Dynamic Tool Discovery

Use --tools=dynamic to let the AI discover endpoints on the fly instead of loading all schemas upfront. This exposes three meta-tools:

1. list_api_endpoints — search available endpoints
2. get_api_endpoint_schema — get schema for a specific endpoint
3. invoke_api_endpoint — call any endpoint

This is useful when context window size is a concern.

Available Tools

Tool	Type	Description
send_messages	write	Send an iMessage, SMS, or MMS to a single recipient
retrieve_messages	read	Retrieve details of a specific message by ID
list_messages	read	List messages with filtering (rate limited: 100 req/10s)
get_status_messages	read	Get current status of a message by handle
send_message_groups	write	Send a message to a group of recipients
modify_groups	write	Add or manage participants in a group chat
upload_media_objects	write	Upload media to Sendblue’s CDN for use in messages
lookup_number_lookups	read	Check if a phone number supports iMessage or SMS
send_typing_indicators	write	Send a typing indicator to a user
create_contacts	write	Create a new contact (or update if update_if_exists is true)
retrieve_contacts	read	Retrieve a contact by phone number
update_contacts	write	Update an existing contact
list_contacts	read	List contacts for your account
delete_contacts	write	Delete a contact
count_contacts	read	Get total contact count
verify_contacts	write	Send a verification message to a contact
create_contacts_bulk	write	Create multiple contacts in bulk
delete_contacts_bulk	write	Delete multiple contacts by ID

Use npx -y sendblue-api-mcp --list to see all available tools from the command line.

Authentication

The MCP server authenticates using your Sendblue API key and secret, passed via environment variables:

Variable	Description
SENDBLUE_API_API_KEY	Your Sendblue API key ID
SENDBLUE_API_API_SECRET	Your Sendblue API secret key

Never commit your API credentials to version control. Use environment variables or a secrets manager.