Servidor MCP de Sinch — Vista previa para desarrolladores

Este repositorio contiene el código fuente del servidor MCP de Sinch, que proporciona un conjunto de herramientas para interactuar con las API de Sinch. Este archivo README se centra en el uso del servidor MCP con el cliente Claude Desktop, pero también puede utilizarse con cualquier otro cliente MCP.

Descripción general de las herramientas

Aquí está la lista de herramientas disponibles en el servidor MCP (todos los números de teléfono deben proporcionarse en formato E.164, p. ej., +33612345678 para Francia).

Herramientas de conversación

Herramientas de correo electrónico (Mailgun)

Herramientas de verificación

Herramientas de voz

Herramientas de números

Herramientas de configuración

Related MCP server: Twilio MCP Server

Introducción

Requisitos previos

• Node.js 20.x o 22.x (LTS)

• Una cuenta de Sinch Build aprovisionada

• Claude Desktop (o cualquier otro cliente MCP). Este README se centra en Claude Desktop, pero el servidor MCP puede utilizarse con cualquier cliente MCP.

Credenciales de API

Para utilizar las API empleadas por las herramientas MCP, necesitará las siguientes credenciales:

• Credenciales de la API de Conversación / Números:

  • (Obligatorio) PROJECT_ID: Seleccione el proyecto que desea utilizar desde su panel de control de Sinch Build (ubicado a la izquierda de la barra de herramientas superior)

  • (Obligatorio) KEY_ID: Seleccione o cree una nueva clave de acceso en la sección de claves de acceso del panel de control de Sinch Build.

  • (Obligatorio) KEY_SECRET: Este es el secreto asociado con la Access Key que seleccionó o creó en el paso anterior. Tenga cuidado, el Access Key Secret solo se muestra una vez cuando crea la Access Key. Si lo pierde, deberá crear una nueva Access Key.

  • CONVERSATION_APP_ID: Este es el ID de la aplicación de conversación que desea utilizar. Puede encontrarlo en la sección de aplicaciones de la API de Conversación del panel de control de Sinch Build. Si no lo configura, deberá especificarlo en el prompt.

  • CONVERSATION_REGION: Esta es la región donde se encuentran su aplicación de conversación y sus plantillas. Puede ser us, eu o br. Si no lo configura, el valor predeterminado es us.

  • Al utilizar el canal SMS, también puede configurar la variable de entorno DEFAULT_SMS_ORIGINATOR con el número de teléfono que se utilizará como remitente para los mensajes SMS. Dependiendo de su país, esta configuración puede ser obligatoria.

  • También puede configurar la variable de entorno GEOCODING_API_KEY con su clave de API de Google Geocoding si desea utilizar la función de ubicación. Esto es necesario para convertir una dirección en un par de latitud/longitud.

• Credenciales de la API de Verificación: navegue a la sección de aplicaciones de Verificación del panel de control de Sinch Build y cree una nueva aplicación o seleccione una existente. Necesitará las siguientes credenciales:

  • (Obligatorio) APPLICATION_KEY

  • (Obligatorio) APPLICATION_SECRET

• Credenciales de la API de Voz: navegue a la sección de aplicaciones de Voz del panel de control de Sinch Build y cree una nueva aplicación o seleccione una existente. Necesitará las siguientes credenciales:

  • (Obligatorio) APPLICATION_KEY

  • (Obligatorio) APPLICATION_SECRET

  • También puede configurar la variable de entorno CALLING_LINE_IDENTIFICATION con el número de teléfono que se mostrará al usuario cuando reciba una llamada.

• Credenciales de la API de Mailgun: navegue a la sección de dominios de Mailgun del panel de control de Mailgun y cree un nuevo dominio o seleccione uno existente. Necesitará las siguientes credenciales:

  • (Obligatorio) MAILGUN_API_KEY

  • MAILGUN_DOMAIN

  • MAILGUN_SENDER_ADDRESS

Configuración del servidor MCP

El servidor MCP de Sinch está disponible como un paquete NPM para ser ejecutado. Aquí le explicamos cómo configurarlo en el archivo de configuración de Claude Desktop (claude_desktop_config.json). Recuerde completar las variables de entorno con sus propias credenciales:

{
  "mcpServers": {
    "sinch": {
      "command": "npx",
      "args": [
        "-y",
        "@sinch/mcp"
      ],
      "env": {
        "PROJECT_ID": "",
        "KEY_ID": "",
        "KEY_SECRET": "",
        "CONVERSATION_APP_ID": "",
        "CONVERSATION_REGION": "",
        "DEFAULT_SMS_ORIGINATOR": "",
        "GEOCODING_API_KEY": "",
        "APPLICATION_KEY": "",
        "APPLICATION_SECRET": "",
        "CALLING_LINE_IDENTIFICATION": "",
        "MAILGUN_API_KEY": "",
        "MAILGUN_DOMAIN": "",
        "MAILGUN_SENDER_ADDRESS": ""
      }
    }
  }
}

Ejecución del servidor MCP localmente

Opción 1: Iniciar el servidor MCP con stdio usando Claude Desktop

Para ejecutar el servidor MCP localmente con Claude Desktop, deberá clonar el repositorio y compilar el servidor MCP. Esta opción es útil para el desarrollo y las pruebas locales.

Paso 1: Clonar el repositorio

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

Paso 2: Compilar el servidor MCP

cd sinch-mcp-server
npm install
npm run build

Paso 3: Configurar Claude Desktop

Aquí hay un ejemplo de cómo configurar el servidor MCP en el archivo de configuración de Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "sinch": {
      "command": "node",
      "args": [
        "/your/path/to/sinch-mcp-server/dist/index.js"
      ],
      "env": {
        "PROJECT_ID": "",
        "KEY_ID": "",
        "KEY_SECRET": "",
        "CONVERSATION_APP_ID": "",
        "CONVERSATION_REGION": "",
        "DEFAULT_SMS_ORIGINATOR": "",
        "GEOCODING_API_KEY": "",
        "APPLICATION_KEY": "",
        "APPLICATION_SECRET": "",
        "CALLING_LINE_IDENTIFICATION": "",
        "MAILGUN_API_KEY": "",
        "MAILGUN_DOMAIN": "",
        "MAILGUN_SENDER_ADDRESS": ""
      }
    }
  }
}

Paso 4: (Opcional) Filtrar las herramientas disponibles en el servidor MCP

Demasiadas herramientas significan un contexto más grande, lo que implica un mayor uso de tokens y más confusión para que el LLM seleccione la herramienta correcta a utilizar. Puede filtrar las herramientas que están disponibles en el servidor MCP utilizando las opciones de tags. Por ejemplo, si solo desea utilizar las herramientas de conversación, puede añadir las siguientes opciones a la matriz args:

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

Puede combinar varias etiquetas separándolas con comas. Por ejemplo, si desea utilizar tanto las herramientas de conversación como las de verificación, puede utilizar el siguiente comando:

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

Si desea utilizar todas las herramientas, puede omitir la opción --tags o utilizar la etiqueta all:

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

Opción 2: Iniciar el servidor MCP de forma remota y conectarse a él mediante SSE

Con esta opción, puede ejecutar el servidor MCP en una máquina remota y conectarse a él mediante Server-Sent Events (SSE). Esto es útil si desea ejecutar el servidor MCP en un servidor en la nube o en una máquina dedicada. De forma predeterminada, Claude Desktop se conectará al servidor MCP mediante STDIO; utilizaremos la biblioteca supergateway para conectarnos al servidor MCP mediante SSE.

Paso 1: Compilar el servidor MCP

cd sinch-mcp-server
npm install
npm run build

Paso 2: Configurar el servidor MCP

Copie el archivo .template.env y cámbiele el nombre a .env. Luego, reemplace los marcadores de posición con sus propias credenciales y elimine cualquier clave que no necesite. El archivo .env debería verse así ():

# Conversation / Numbers tools related environment variables
PROJECT_ID=
KEY_ID=
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=

# Verification / Voice tools related environment variables
APPLICATION_KEY=
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=

Paso 3: Iniciar el servidor MCP

npm run start:stdio

De forma predeterminada, este comando iniciará el MCP con todas las herramientas disponibles. Si desea filtrar las herramientas que están disponibles en el servidor MCP, puede utilizar la opción --tags. Por ejemplo, si solo desea utilizar las herramientas de conversación, puede modificar el comando de la siguiente manera:

# Original command
"start:sse": "tsc --project tsconfig.build.json && (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:sse": "tsc --project tsconfig.build.json && (npx -y supergateway --stdio \"node dist/index.js --tag conversation\" --port 8000 --baseUrl http://localhost:8000 --ssePath /sse --messagePath /message)"

Puede combinar varias etiquetas separándolas con comas. Por ejemplo, si desea utilizar tanto las herramientas de conversación como las de verificación, puede utilizar el siguiente comando:

"start": "tsc --project tsconfig.build.json && (npx -y supergateway --stdio \"node dist/index.js --tag conversation,verification\" --port 8000 --baseUrl http://localhost:8000 --ssePath /sse --messagePath /message)"

Paso 4: Configurar el servidor MCP en Claude Desktop

A continuación, puede configurar el servidor MCP en el archivo de configuración de Claude de la siguiente manera:

{
  "mcpServers": {
    "sinch": {
      "command": "npx",
      "args": [
        "-y", "supergateway", "--sse", "http://localhost:8000/sse"
      ]
    }
  }
}

(Reemplace http://localhost:8000/sse con la URL de su servidor MCP si no se está ejecutando localmente)

Contribución: Definición de nuevas herramientas

Las herramientas se registran en el archivo src/index.ts.

• Herramientas de conversación: enviar