Sinch MCP Server

🚀 Sinch MCP Server — Developer Preview

This repository contains the source code for the Sinch MCP server, which offers a suite of tools to interact with the Sinch APIs. While this README focuses on using the MCP server with the Claude Desktop client, it's also compatible with any other MCP client.

✨ Features

Tools Overview

Here's a list of the tools available in the MCP server. Note that all phone numbers must be provided in E.164 format (e.g., +33612345678 for France).

Conversation Tools

Email tools (Mailgun)

Verification Tools

Voice Tools

Configuration Tools

🚀 Quick Start

Prerequisites

• Node.js >= 20.18.1
• A provisioned Sinch Build account
• Claude Desktop (or any other MCP client). This README focuses on Claude Desktop, but the MCP server can be used with any MCP client.

API credentials

To use the APIs utilized by the MCP tools, you'll need the following credentials:

• Conversation API credentials:
  • (Required) CONVERSATION_PROJECT_ID: Select the project you want to use from your Sinch Build dashboard (Located at the left of the top toolbar).
  • (Required) CONVERSATION_KEY_ID: Select or create a new access key in the Access keys section of the Sinch Build dashboard.
  • (Required) CONVERSATION_KEY_SECRET: This is the secret associated with the Access Key you selected or created in the previous step. Be cautious, as the Access Key Secret is only shown once when you create the Access Key. If you lose it, you'll need to create a new Access Key.
  • 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 of the Sinch Build dashboard. If you don't set it, you'll have to specify it in the prompt.
  • 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.
  • When using 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.
  • NGROK_AUTH_TOKEN: If you want to use the tool get-message-events, you have to be able to receive events related to a message. If this variable is set, the MCP server will open a tunnel to your local machine using ngrok. If you don't set this variable, the MCP server will not be able to receive events related to a message.
• Verification API credentials: Navigate to the Verification / Apps section of the Sinch Build dashboard and create a new app or select an existing one. You'll need the following credentials:
  • (Required) VERIFICATION_APPLICATION_KEY
  • (Required) VERIFICATION_APPLICATION_SECRET
• Voice API credentials: Navigate to the Voice / Apps section of the Sinch Build dashboard and create a new app or select an existing one. You'll need the following credentials:
  • (Required) VOICE_APPLICATION_KEY
  • (Required) 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 of the Mailgun dashboard and create a new domain or select an existing one. You'll need the following credentials:
  • (Required) MAILGUN_API_KEY
  • MAILGUN_DOMAIN
  • MAILGUN_SENDER_ADDRESS

MCP Server Configuration

The Sinch MCP server is available as an NPM package for execution. Here's how to set it up in the Claude Desktop configuration file (claude_desktop_config.json). Remember to populate the environment variables with your own credentials:

{
  "mcpServers": {
    "sinch": {
      "command": "npx",
      "args": [
        "-y",
        "@sinch/mcp"
      ],
      "env": {
        "CONVERSATION_PROJECT_ID": "",
        "CONVERSATION_KEY_ID": "",
        "CONVERSATION_KEY_SECRET": "",
        "CONVERSATION_APP_ID": "",
        "CONVERSATION_REGION": "",
        "DEFAULT_SMS_ORIGINATOR": "",
        "GEOCODING_API_KEY": "",
        "NGROK_AUTH_TOKEN": "",
        "VERIFICATION_APPLICATION_KEY": "",
        "VERIFICATION_APPLICATION_SECRET": "",
        "VOICE_APPLICATION_KEY": "",
        "VOICE_APPLICATION_SECRET": "",
        "CALLING_LINE_IDENTIFICATION": "",
        "MAILGUN_API_KEY": "",
        "MAILGUN_DOMAIN": "",
        "MAILGUN_SENDER_ADDRESS": ""
      }
    }
  }
}

📦 Installation

Running the MCP Server locally

Option 1: Start the MCP server with stdio using Claude Desktop

To run the MCP server locally with Claude Desktop, you'll need to clone the repository and build the MCP server. This option is ideal for local development and testing.

Step 1: Clone the repository

git clone https://github.com/sinch/sinch-mcp-server.git

Step 2: Build the MCP server

cd sinch-mcp-server
npm install
npm run build

Step 3: Setup Claude Desktop configuration

Here's an example of how to configure the MCP server in the Claude Desktop configuration file (claude_desktop_config.json):

{
  "mcpServers": {
    "sinch": {
      "command": "node",
      "args": [
        "/your/path/to/sinch-mcp-server/dist/index.js"
      ],
      "env": {
        "CONVERSATION_PROJECT_ID": "",
        "CONVERSATION_KEY_ID": "",
        "CONVERSATION_KEY_SECRET": "",
        "CONVERSATION_APP_ID": "",
        "CONVERSATION_REGION": "",
        "DEFAULT_SMS_ORIGINATOR": "",
        "GEOCODING_API_KEY": "",
        "NGROK_AUTH_TOKEN": "",
        "VERIFICATION_APPLICATION_KEY": "",
        "VERIFICATION_APPLICATION_SECRET": "",
        "VOICE_APPLICATION_KEY": "",
        "VOICE_APPLICATION_SECRET": "",
        "CALLING_LINE_IDENTIFICATION": "",
        "MAILGUN_API_KEY": "",
        "MAILGUN_DOMAIN": "",
        "MAILGUN_SENDER_ADDRESS": ""
      }
    }
  }
}

Step 4: (Optional) Filter the tools available in the MCP server

Too many tools can lead to a larger context, higher token usage, and more confusion for the LLM when selecting the appropriate tool. You can filter the available tools in the MCP server using the tags option. For example, if you only want to use the conversation tools, you can add the following options to the args array:

      "args": [
        "/your/path/to/sinch-mcp-server/dist/index.js",
        "--tags", 
        "conversation"
      ],

You can combine multiple tags by separating them with commas. For instance, if you want to use both conversation and verification tools, you can use the following command:

      "args": [
        "/your/path/to/sinch-mcp-server/dist/index.js",
        "--tags", 
        "conversation,verification"
      ],

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/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'll use the supergateway library to connect to the MCP server using SSE.

Step 1: Build the MCP server

cd sinch-mcp-server
npm install
npm run build

Step 2: Set up the MCP server configuration

Copy the file .template.env 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:

# Conversation tools related environment variables
CONVERSATION_PROJECT_ID=
CONVERSATION_KEY_ID=
CONVERSATION_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=
## Optional, defaults to "us". Other possible values are "eu" and "br"
CONVERSATION_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=
## Needed only if you want to send location messages: it converts an address to a latitude/longitude pair
GEOCODING_API_KEY=
## Token to be obtained at https://dashboard.ngrok.com/get-started/your-authtoken to enable the "get-message-events" tool
NGROK_AUTH_TOKEN=

# Verification tools related environment variables
VERIFICATION_APPLICATION_KEY=
VERIFICATION_APPLICATION_SECRET=

# Voice tools related environment variables (Application key and secret can be the same as for Verification)
VOICE_APPLICATION_KEY=
VOICE_APPLICATION_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=

# Mailgun tools related environment variables
MAILGUN_DOMAIN=
MAILGUN_API_KEY=
MAILGUN_SENDER_ADDRESS=

Step 3: Start the MCP server

npm run start

By default, this command will start the MCP with all the tools available. If you want to filter the available tools in the MCP server, you can use the --tags option. For example, if you only want to use the conversation tools, you can modify the command as follows:

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

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

{
  "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's not running locally)

📚 Documentation

Contributing: Defining new tools

Tools are registered in the src/index.ts file.

• Conversation tools: Send various types of messages, list conversation 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