Overview
Clerk Chat provides an MCP (Model Context Protocol) server that lets you send messages, manage contacts, and run campaigns from any MCP-compatible client. The MCP server is hosted at:Prerequisites
- A Clerk Chat account with an active workspace
- An MCP-compatible client (e.g., Claude Code, Claude Desktop, or any other MCP client)
Authentication
The Clerk Chat MCP server uses OAuth for authentication. The first time you invoke a tool, your client will open a browser window to authenticate with your Clerk Chat account. After signing in, you’ll be redirected back and the session will be active.Claude Code Setup
Add the Clerk Chat MCP server to Claude Code:Authentication successful. Connected to clerk. in the output.
Available Tools
Once connected, the following tools are available:send_message
Send an SMS/MMS message from a Clerk Chat inbox.| Parameter | Type | Required | Description |
|---|---|---|---|
sender | string | Yes | The Clerk phone number to send from (e.g., +15551234567) |
recipients | string[] | Yes | List of recipient phone numbers |
body | string | Yes | The message text content |
media_urls | string[] | No | Media URLs to attach (for MMS) |
sent_by_name | string | No | Display name for the sender |
get_messages
Retrieve messages for the active team with optional filtering.| Parameter | Type | Required | Description |
|---|---|---|---|
inbox_ids | string[] | No | Filter by specific inbox IDs |
start | string | No | Start datetime in ISO format |
end | string | No | End datetime in ISO format |
limit | integer | No | Max messages to return (default: 50, max: 50) |
page | integer | No | Page number for pagination (default: 1) |
create_contact
Create a new contact in your workspace.| Parameter | Type | Required | Description |
|---|---|---|---|
name | string | No | Contact name |
email | string | No | Contact email |
phone | string | No | Contact phone number |
public | boolean | No | Visible to all team members |
data | object | No | Additional metadata key-value pairs |
update_contact
Update an existing contact.| Parameter | Type | Required | Description |
|---|---|---|---|
contact_id | string | Yes | The contact ID to update |
name | string | No | New name |
email | string | No | New email |
phone | string | No | New phone number |
public | boolean | No | Visibility setting |
data | object | No | Metadata (replaces existing) |
delete_contact
Delete a contact by ID.| Parameter | Type | Required | Description |
|---|---|---|---|
contact_id | string | Yes | The contact ID to delete |
create_contacts_batch
Create multiple contacts at once.| Parameter | Type | Required | Description |
|---|---|---|---|
contacts | object[] | Yes | Array of contact objects (same fields as create_contact) |
create_campaign
Send a message to all contacts in a list.| Parameter | Type | Required | Description |
|---|---|---|---|
sender | string | Yes | The Clerk phone number to send from |
list_name | string | Yes | Name of the recipient list |
body | string | Yes | Message content |
media_urls | string[] | No | Media URLs to attach |
name | string | No | Campaign name |
timestamp | string | No | Scheduled send time (ISO format) |
provider | string | No | SMS provider (twilio, bandwidth, telnyx, etc.) |
Examples
Send a message:Send a message from +15551234567 to +15559876543 saying “Your appointment is confirmed for tomorrow at 2pm”Check recent messages:
Show me the last 10 messages from inbox 5d0e8d03-d09f-47e5-8017-4d00cbf737f4Create a contact:
Create a contact for Jane Smith with phone +15551234567 and email [email protected]
Troubleshooting
| Issue | Solution |
|---|---|
Session not found error | Run /mcp to reconnect |
Authentication failed | Run /mcp to clear and re-authenticate |
| Tools not appearing | Run /mcp to reconnect, then retry |
Unauthorized errors on tool calls | Your OAuth token may have expired. Run /mcp to re-authenticate |