# Sinch MCP Server Tools Overview
Here is the list of tools available in the MCP server (all the phone numbers must be provided in E.164 format, e.g., `+33612345678` for France).
## Conversation Tools
| Tool | Description | Tags |
|------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------|
| **send-text-message** | Send a plain text message to a recipient on a supported channel.
*Example prompt*: "Send a quick update to the phone number +33612345678 on SMS." | conversation, notification |
| **send-media-message** | Send an image, video, or document via a media message.
*Example prompt*: "Send the product brochure PDF to the phone number +33612345678 on WhatsApp." | conversation, notification |
| **send-template-message** | Send a message using a predefined template (e.g., WhatsApp or omni-template).
*Example prompt*: "Send the appointment reminder template in Spanish to this user on Messenger." | conversation, notification |
| **send-choice-message** | Send a message that includes interactive choices (buttons or quick replies).
*Example prompt*: "Send a RCS survey about preferred ice cream flavor to +33662162504 with the following choices: Vanilla, Strawberry, Hazelnut". | conversation, notification |
| **send-location-message** | Send a location pin or coordinates to a user.
*Example prompt*: "Send a pin to the Guggenheim Museum location in Bilbao to the phone number +33612345678." | conversation, notification |
| **list-all-apps** | List all configured Conversation apps in the Sinch account.
*Example prompt*: "What messaging apps do I have set up in my account?" | conversation, notification |
| **list-messaging-templates** | List all omni-channel and channel-specific message templates.
*Example prompt*: "Show me all message templates in my account." | conversation, notification |
## Email tools (Mailgun)
| Tool | Description | Tags |
|--------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------|
| **send-email** | Send an email using a predefined HTML template or raw HTML/text content.
*Example prompt*: "Send a welcome email to [john@example.com](mailto:john@example.com) using our onboarding template." | email, notification |
| **list-email-templates** | List all email templates available for a specific domain.
*Example prompt*: "What email templates do I have available?" | email, notification |
| **retrieve-email-info** | Retrieve metadata, content and delivery status for a specific email message.
*Example prompt*: "Can you get the delivery status of the email with ID ?" | email, notification |
| **list-email-events** | Retrieve and group recent email delivery events, such as bounces, opens, or clicks.
*Example prompt*: "Show me all recent email activity for my account." | email |
| **analytics-metrics** | Retrieve email analytics metrics, such as open rates or click-through rates.
*Example prompt*: "What are the open rates during the last week?" | email |
## Verification Tools
| Tool | Description | Tags |
|-----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------|
| **number-lookup** | Lookup a phone number for its status and capabilities.
*Example prompt*: "Lookup for the following phone number capabilities: +33501020304." | verification |
| **start-sms-verification** | Initiate an SMS verification by sending an OTP to a user's phone number.
*Example prompt*: "Start phone verification for the number +33612345678." | verification |
| **report-sms-verification** | Submit a one-time password (OTP) to complete SMS verification.
*Example prompt*: "Verify the phone number with this code: 1234." | verification |
## Voice Tools
| Tool | Description | Tags |
|-----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------|
| **tts-callout** | Place a voice call and read aloud a message using Text-to-Speech.
*Example prompt*: "Call the phone number +33612345678 and say: 'Your appointment is tomorrow at 10 AM.'" | voice, notification |
| **conference-call** | Start a voice call to one or more participants and connect them to a shared conference.
*Example prompt*: "Call John (+33612345678) and Lisa (+34987654321) and connect them to a conference room." | voice |
| **manage-conference-participant** | Mute, unmute, hold, or resume an individual participant in a conference call.
*Example prompt*: "Mute the caller with ID xyz789 in the conference." | voice |
| **close-conference** | End a conference call by disconnecting all the participants using the ID of the conference.
*Example prompt*: "End the current conference call with ID abc123." | voice |
## Getting Started
### 0. Prerequisites
- Node.js >= 20.18.1
- npm >= 9
- A provisioned [Sinch Build account](https://dashboard.sinch.com/dashboard)
- Claude Desktop (or any other MCP client). This README is focused on Claude Desktop, but the MCP server can be used with any MCP client.
- Clone this repository
```bash
git clone https://github.com/sinch/sinch-mcp-server.git
```
### 1. API credentials
To use the APIs used by the MCP tools, you will need the following credentials:
- Conversation API credentials:
- CONVERSATION_PROJECT_ID: Select the project you want to use from your [Sinch Build dashboard](https://dashboard.sinch.com/dashboard) (Located at the left of the top toolbar)
- CONVERSATION_KEY_ID: Select or create a new access key in the [Access keys section](https://dashboard.sinch.com/settings/access-keys) of the Sinch Build dashboard.
- CONVERSATION_KEY_SECRET: This is the secret associated with the `Access Key` you selected or created in the previous step. Be careful, the `Access Key Secret` is only shown once when you create the `Access Key`. If you lose it, you will need to create a new `Access Key`.
- CONVERSATION_REGION: This is the region where your conversation app and templates are located. It can be `us`, `eu`, or `br`. If you don't set it, it defaults to `us`.
- CONVERSATION_APP_ID: This is the ID of the conversation app you want to use. You can find it in the [Conversation API / Apps section](https://dashboard.sinch.com/convapi/apps) of the Sinch Build dashboard. If you don't set it, you will have to specify it in the prompt.
- In case you want to use the SMS channel, you can also set the `DEFAULT_SMS_ORIGINATOR` environment variable to the phone number that will be used as the sender for SMS messages. Depending on your country, this setting may be required.
- You can also set the `GEOCODING_API_KEY` environment variable to your Google Geocoding API key if you want to use the location feature. This is needed to convert an address to a latitude/longitude pair.
- Verification API credentials: navigate to the [Verification / Apps section](https://dashboard.sinch.com/verification/apps) of the Sinch Build dashboard and create a new app or select an existing one. You will need the following credentials:
- VERIFICATION_APPLICATION_KEY
- VERIFICATION_APPLICATION_SECRET
- Voice API credentials: navigate to the [Voice / Apps section](https://dashboard.sinch.com/voice/apps) of the Sinch Build dashboard and create a new app or select an existing one. You will need the following credentials:
- VOICE_APPLICATION_KEY
- VOICE_APPLICATION_SECRET
- You can also set the `CALLING_LINE_IDENTIFICATION` environment variable to the phone number that will be displayed to the user when they receive a call.
- Mailgun API credentials: navigate to the [Mailgun / Domains section](https://app.mailgun.com/app/domains) of the Mailgun dashboard and create a new domain or select an existing one. You will need the following credentials:
- MAILGUN_DOMAIN
- MAILGUN_API_KEY
- MAILGUN_SENDER_ADDRESS
## Option 1: Start the MCP server with stdio using Claude Desktop
### Step 1: Build the MCP server
```bash
cd sinch-mcp-server/mcp
npm install
npm run build
```
### Step 2: Setup Claude Desktop configuration
Here is an example of how to configure the MCP server in the [Claude Desktop](https://claude.ai/download) configuration file (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"sinch": {
"command": "node",
"args": [
"/your/path/to/sinch-mcp-server/mcp/dist/index.js"
],
"env": {
"CONVERSATION_PROJECT_ID": "YOUR_PROJECT_ID",
"CONVERSATION_KEY_ID": "YOUR_ACCESS_KEY_ID",
"CONVERSATION_KEY_SECRET": "YOUR_ACCESS_KEY_SECRET",
"CONVERSATION_REGION": "YOUR_REGION (optional, default to US)",
"DEFAULT_SMS_ORIGINATOR": "YOUR_DEFAULT_SMS_ORIGINATOR (required in some countries if you want to send SMS messages)",
"GEOCODING_API_KEY": "YOUR_GOOGLE_GEOCODING_API_KEY (optional, needed only if you want to send location messages)",
"VERIFICATION_APPLICATION_KEY": "YOUR_VERIFICATION_APP_KEY",
"VERIFICATION_APPLICATION_SECRET": "YOUR_VERIFICATION_APP_SECRET",
"VOICE_APPLICATION_KEY": "YOUR_VOICE_APP_KEY",
"VOICE_APPLICATION_SECRET": "YOUR_VOICE_APP_SECRET",
"CALLING_LINE_IDENTIFICATION": "YOUR_CALLING_NUMBER",
"MAILGUN_DOMAIN": "YOUR_MAILGUN_DOMAIN",
"MAILGUN_API_KEY": "YOUR_MAILGUN_API_KEY",
"MAILGUN_SENDER_ADDRESS": "YOUR_MAILGUN_SENDER_ADDRESS"
}
}
}
}
```
You can filter the tools that are available in the MCP server by using the `tags` options. For example, if you want to only use the conversation tools, you can add the following options to the `args` array:
```
"args": [
"/your/path/to/sinch-mcp-server/mcp/dist/index.js",
"--tags",
"conversation"
],
```
If you want to use all the tools, you can omit the `--tags` option, or use the tag `all`:
```
"args": [
"/your/path/to/sinch-mcp-server/mcp/dist/index.js",
"--tags",
"all"
],
```
## Option 2: Start the MCP server remotely and connect to it using SSE
With this option, you can run the MCP server on a remote machine and connect to it using Server-Sent Events (SSE). This is useful if you want to run the MCP server on a cloud server or a dedicated machine.
By default, Claude Desktop will connect to the MCP server using STDIO; we will use the [supergateway library](https://github.com/supercorp-ai/supergateway) to connect to the MCP server using SSE.
### Step 1: Build the MCP server
```bash
cd sinch-mcp-server/mcp
npm install
npm run build
```
### Step 2: Set up the MCP server configuration
Copy the file `.template.env` located at `./mcp` and rename it `.env`. Then replace the placeholders with your own credentials and delete any key you don't need. The `.env` file should look like this ():
```dotenv
# Conversation tools related environment variables
CONVERSATION_PROJECT_ID=YOUR_PROJECT_ID
CONVERSATION_KEY_ID=YOUR_ACCESS_KEY_ID
CONVERSATION_KEY_SECRET=YOUR_ACCESS_KEY_SECRET
## Optional but recommended: the App ID holding your channels integration configuration. If not set it must be present in the prompt
CONVERSATION_APP_ID=YOUR_CONVERSATION_APP_ID
## Optional, defaults to "us". Other possible values are "eu" and "br"
CONVERSATION_REGION=YOUR_REGION
## Needed only if you want to send SMS messages: it is the number that will be used as the sender for SMS messages
DEFAULT_SMS_ORIGINATOR=YOUR_SINCH_PHONE_NUMBER
## Needed only if you want to send location messages: it converts an address to a lat/lon
GEOCODING_API_KEY=YOUR_GOOGLE_GEOCODING_API_KEY
# Verification tools related environment variables
VERIFICATION_APPLICATION_KEY=YOUR_APP_KEY
VERIFICATION_APPLICATION_SECRET=YOUR_APP_SECRET
# Voice tools related environment variables (Application key and secret can be the same as for Verification)
VOICE_APPLICATION_KEY=YOUR_APP_KEY
VOICE_APPLICATION_SECRET=YOUR_APP_SECRET
## Needed only if you want to make calls: it is the number that will be displayed to the user when they receive a call
CALLING_LINE_IDENTIFICATION=YOUR_CALLING_NUMBER
# Mailgun tools related environment variables
MAILGUN_DOMAIN=YOUR_MAILGUN_DOMAIN
MAILGUN_API_KEY=YOUR_MAILGUN_API_KEY
MAILGUN_SENDER_ADDRESS=YOUR_MAILGUN_SENDER_ADDRESS
```
### Step 3: Start the MCP server
```bash
npm run start
```
By default, this command will start the MCP with all the tools available. If you want to filter the tools that are available in the MCP server, you can use the `--tags` option. For example, if you want to only use the conversation tools, you can modify the command as follows:
```bash
# Original command
"start": "tsc && (npx -y supergateway --stdio \"node dist/index.js\" --port 8000 --baseUrl http://localhost:8000 --ssePath /sse --messagePath /message)"
# Modified command to only use conversation tools
"start": "tsc && (npx -y supergateway --stdio \"node dist/index.js --tag conversation\" --port 8000 --baseUrl http://localhost:8000 --ssePath /sse --messagePath /message)"
```
You can combine multiple tags by separating them with commas. For example, if you want to use both conversation and verification tools, you can use the following command:
```bash
"start": "tsc && (npx -y supergateway --stdio \"node dist/index.js --tag conversation,verification\" --port 8000 --baseUrl http://localhost:8000 --ssePath /sse --messagePath /message)"
```
### Step 4: Configure the MCP server in Claude Desktop
You can then configure the MCP server in the Claude configuration file as follows:
```json
{
"mcpServers": {
"sinch": {
"command": "npx",
"args": [
"-y", "supergateway", "--sse", "http://localhost:8000/sse"
]
}
}
}
```
(Replace the `http://localhost:8000/sse` with the URL of your MCP server if it is not running locally)
## Contributing: Defining new tools
Tools are registered in the `src/index.ts` file.
- Conversation tools: send various types of messages, list conversations apps, templates
- Verification tools: lookup for a number, perform a verification flow
- Voice tools: make a TTS call, create a conference call, manage participants
- Email tools: send emails, retrieve email information
Tools are defined under `src/tools/` and are registered in the `index.ts` file of their respective domain folder.
- Conversation tools: `src/tools/conversation/index.ts`
- Verification tools: `src/tools/verification/index.ts`
- Voice tools: `src/tools/voice/index.ts`
- Email tools: `src/tools/email/index.ts`