---
title: Model Context Protocol (MCP) | Sendblue Docs
description: Connect AI editors and agents to the Sendblue API using MCP for messaging, contacts, and more.
---

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`:

Terminal window

```
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](https://sendblue.com/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

Terminal window

```
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:

Terminal window

```
# 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.