Sinch MCP Server

🚀 Sinch MCP 服务器 — 开发者预览版

本仓库包含 Sinch MCP 服务器的源代码，该服务器提供了一组与 Sinch API 进行交互的工具。本 README 主要聚焦于将 MCP 服务器与 Claude Desktop 客户端配合使用，但它也可以与任何其他 MCP 客户端一起使用。

✨ 主要特性

工具概述

以下是 MCP 服务器中可用的工具列表（所有电话号码必须采用 E.164 格式，例如，法国的电话号码为 +33612345678）。

对话工具

电子邮件工具（Mailgun）

验证工具

语音工具

配置工具

🚀 快速开始

前提条件

• Node.js >= 20.18.1
• 已配置的 Sinch Build 账户
• Claude Desktop（或任何其他 MCP 客户端）。本 README 主要关注 Claude Desktop，但 MCP 服务器可以与任何 MCP 客户端一起使用。

API 凭证

要使用 MCP 工具所使用的 API，您需要以下凭证：

• 对话 API 凭证：
  • （必需）CONVERSATION_PROJECT_ID：从 Sinch Build 控制台 中选择您要使用的项目（位于顶部工具栏左侧）
  • （必需）CONVERSATION_KEY_ID：在 Sinch Build 控制台的 访问密钥部分 中选择或创建一个新的访问密钥。
  • （必需）CONVERSATION_KEY_SECRET：这是您在前面步骤中选择或创建的 访问密钥 关联的密钥。请注意，访问密钥密钥 在创建 访问密钥 时仅显示一次。如果您丢失了它，您需要创建一个新的 访问密钥。
  • CONVERSATION_APP_ID：这是您要使用的对话应用程序的 ID。您可以在 Sinch Build 控制台的 对话 API / 应用程序部分 中找到它。如果您未设置它，则需要在提示中指定。
  • CONVERSATION_REGION：这是您的对话应用程序和模板所在的区域。可以是 us、eu 或 br。如果您未设置它，默认值为 us。
  • 使用短信渠道时，您还可以将 DEFAULT_SMS_ORIGINATOR 环境变量设置为将用作短信消息发件人的电话号码。根据您所在的国家/地区，此设置可能是必需的。
  • 如果您想使用位置功能，还可以将 GEOCODING_API_KEY 环境变量设置为您的 Google 地理编码 API 密钥。这是将地址转换为纬度/经度对所必需的。
  • NGROK_AUTH_TOKEN：如果您想使用 get-message-events 工具，您必须能够接收与消息相关的事件。如果设置了此变量，MCP 服务器将使用 ngrok 打开一个到您本地机器的隧道。如果您未设置此变量，MCP 服务器将无法接收与消息相关的事件。
• 验证 API 凭证：导航到 Sinch Build 控制台的 验证 / 应用程序部分 并创建一个新应用程序或选择一个现有应用程序。您需要以下凭证：
  • （必需）VERIFICATION_APPLICATION_KEY
  • （必需）VERIFICATION_APPLICATION_SECRET
• 语音 API 凭证：导航到 Sinch Build 控制台的 语音 / 应用程序部分 并创建一个新应用程序或选择一个现有应用程序。您需要以下凭证：
  • （必需）VOICE_APPLICATION_KEY
  • （必需）VOICE_APPLICATION_SECRET
  • 您还可以将 CALLING_LINE_IDENTIFICATION 环境变量设置为用户接听电话时将显示的电话号码。
• Mailgun API 凭证：导航到 Mailgun 控制台的 Mailgun / 域名部分 并创建一个新域名或选择一个现有域名。您需要以下凭证：
  • （必需）MAILGUN_API_KEY
  • MAILGUN_DOMAIN
  • MAILGUN_SENDER_ADDRESS

MCP 服务器配置

Sinch MCP 服务器以 NPM 包的形式提供。以下是如何在 Claude Desktop 配置文件 (claude_desktop_config.json) 中进行设置。请记住用您自己的凭证填充环境变量：

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

📦 安装指南

在本地运行 MCP 服务器

选项 1：使用 Claude Desktop 通过标准输入输出启动 MCP 服务器

要使用 Claude Desktop 在本地运行 MCP 服务器，您需要克隆仓库并构建 MCP 服务器。此选项适用于本地开发和测试。

1. 步骤 1：克隆仓库

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

2. 步骤 2：构建 MCP 服务器

cd sinch-mcp-server
npm install
npm run build

3. 步骤 3：设置 Claude Desktop 配置 以下是如何在 Claude Desktop 配置文件 (claude_desktop_config.json) 中配置 MCP 服务器的示例：

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

4. 步骤 4：（可选）过滤 MCP 服务器中可用的工具 工具太多意味着上下文更大，意味着使用的令牌更多，并且大语言模型（LLM）选择正确工具时会更加困惑。 您可以使用 tags 选项过滤 MCP 服务器中可用的工具。例如，如果您只想使用对话工具，可以在 args 数组中添加以下选项：

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

您可以用逗号分隔多个标签。例如，如果您想同时使用对话和验证工具，可以使用以下命令：

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

如果您想使用所有工具，可以省略 --tags 选项，或使用标签 all：

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

选项 2：远程启动 MCP 服务器并使用 Server-Sent Events (SSE) 连接到它

使用此选项，您可以在远程机器上运行 MCP 服务器并使用 Server-Sent Events (SSE) 连接到它。如果您想在云服务器或专用机器上运行 MCP 服务器，这很有用。 默认情况下，Claude Desktop 将使用标准输入输出连接到 MCP 服务器；我们将使用 supergateway 库 通过 SSE 连接到 MCP 服务器。

1. 步骤 1：构建 MCP 服务器

cd sinch-mcp-server
npm install
npm run build

2. 步骤 2：设置 MCP 服务器配置 复制 .template.env 文件并将其重命名为 .env。然后用您自己的凭证替换占位符，并删除任何您不需要的键。.env 文件应如下所示：

# 对话工具相关环境变量
CONVERSATION_PROJECT_ID=
CONVERSATION_KEY_ID=
CONVERSATION_KEY_SECRET=
## 可选但推荐：保存您的渠道集成配置的应用程序 ID。如果未设置，则必须在提示中包含
CONVERSATION_APP_ID=
## 可选，默认为 "us"。其他可能的值为 "eu" 和 "br"
CONVERSATION_REGION=
## 仅在您想发送短信时需要：它是将用作短信消息发件人的号码
DEFAULT_SMS_ORIGINATOR=
## 仅在您想发送位置消息时需要：它将地址转换为纬度/经度对
GEOCODING_API_KEY=
## 在 https://dashboard.ngrok.com/get-started/your-authtoken 获取的令牌，以启用 "get-message-events" 工具
NGROK_AUTH_TOKEN=

# 验证工具相关环境变量
VERIFICATION_APPLICATION_KEY=
VERIFICATION_APPLICATION_SECRET=

# 语音工具相关环境变量（应用程序密钥和密钥可以与验证工具相同）
VOICE_APPLICATION_KEY=
VOICE_APPLICATION_SECRET=
## 仅在您想打电话时需要：它是用户接听电话时将显示的号码
CALLING_LINE_IDENTIFICATION=

# Mailgun 工具相关环境变量
MAILGUN_DOMAIN=
MAILGUN_API_KEY=
MAILGUN_SENDER_ADDRESS=

3. 步骤 3：启动 MCP 服务器

npm run start

默认情况下，此命令将启动包含所有可用工具的 MCP。如果您想过滤 MCP 服务器中可用的工具，可以使用 --tags 选项。例如，如果您只想使用对话工具，可以将命令修改如下：

# 原始命令
"start": "tsc && (npx -y supergateway --stdio \"node dist/index.js\" --port 8000 --baseUrl http://localhost:8000 --ssePath /sse --messagePath /message)"

# 修改后的命令，仅使用对话工具
"start": "tsc && (npx -y supergateway --stdio \"node dist/index.js --tag conversation\" --port 8000 --baseUrl http://localhost:8000 --ssePath /sse --messagePath /message)"

您可以用逗号分隔多个标签。例如，如果您想同时使用对话和验证工具，可以使用以下命令：

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

4. 步骤 4：在 Claude Desktop 中配置 MCP 服务器 然后，您可以在 Claude 配置文件中按如下方式配置 MCP 服务器：

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

（如果 MCP 服务器不是在本地运行，请将 http://localhost:8000/sse 替换为您的 MCP 服务器的 URL）

🔧 技术细节

贡献：定义新工具

工具在 src/index.ts 文件中注册。

• 对话工具：发送各种类型的消息、列出对话应用程序和模板
• 验证工具：查找号码、执行验证流程
• 语音工具：进行文本转语音通话、创建会议通话、管理参与者
• 电子邮件工具：发送电子邮件、检索电子邮件信息

工具定义在 src/tools/ 下，并在各自领域文件夹的 index.ts 文件中注册。

• 对话工具：src/tools/conversation/index.ts
• 验证工具：src/tools/verification/index.ts
• 语音工具：src/tools/voice/index.ts
• 电子邮件工具：src/tools/email/index.ts