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

Name: Sinch MCP Server
Author: sinch

Latest Release

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

工具概览

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

会话工具

工具	描述	标签
send-text-message	向支持的渠道上的收件人发送纯文本消息。提示示例：“向电话号码 +33612345678 发送一条短信更新。”	conversation, notification
send-media-message	通过媒体消息发送图像、视频或文档。提示示例：“通过 WhatsApp 向电话号码 +33612345678 发送产品手册 PDF。”	conversation, notification
send-template-message	使用预定义模板发送消息（仅限 omni-template）。提示示例：“向该用户发送西班牙语的预约提醒模板（通过 Messenger）。”	conversation, notification
send-whatsapp-template-message	使用预定义的 WhatsApp 模板发送消息。提示示例：“使用 WhatsApp 上的“appointment-reminder”模板发送消息。”	conversation, notification
send-choice-message	发送包含交互式选项（按钮或快速回复）的消息。提示示例：“向 +33612345678 发送关于首选冰淇淋口味的 RCS 调查，选项包括：香草、草莓、榛子”。	conversation, notification
send-location-message	向用户发送位置图钉或坐标。提示示例：“向电话号码 +33612345678 发送毕尔巴鄂古根海姆博物馆的位置图钉。”	conversation, notification
list-conversation-apps	列出 Sinch 账户中所有已配置的会话应用程序。提示示例：“我的账户中设置了哪些消息应用程序？”	conversation, notification
list-messaging-templates	列出所有全渠道和特定渠道的消息模板。提示示例：“向我展示账户中的所有消息模板。”	conversation, notification

电子邮件工具 (Mailgun)

工具	描述	标签
send-email	使用预定义的 HTML 模板或原始 HTML/文本内容发送电子邮件。提示示例：“使用我们的入职模板向 john@example.com 发送欢迎邮件。”	email, notification
list-email-templates	列出特定域名下可用的所有电子邮件模板。提示示例：“我有哪些可用的电子邮件模板？”	email, notification
retrieve-email-info	获取特定电子邮件的元数据、内容和投递状态。提示示例：“你能获取 ID 为的邮件的投递状态吗？”	email, notification
list-email-events	获取并分组最近的电子邮件投递事件，例如退信、打开或点击。提示示例：“向我展示我账户中最近的所有电子邮件活动。”	email
analytics-metrics	获取电子邮件分析指标，例如打开率或点击率。提示示例：“上周的打开率是多少？”	email

验证工具

工具	描述	标签
number-lookup	查询电话号码的状态和功能。提示示例：“查询以下电话号码的功能：+33501020304。”	verification
start-sms-verification	通过向用户的电话号码发送 OTP 来启动短信验证。提示示例：“开始对号码 +33612345678 进行电话验证。”	verification
report-sms-verification	提交一次性密码 (OTP) 以完成短信验证。提示示例：“使用此代码验证电话号码：1234。”	verification

语音工具

工具	描述	标签
tts-callout	拨打语音电话并使用文本转语音 (TTS) 朗读消息。提示示例：“拨打电话号码 +33612345678 并说：‘您的预约在明天上午 10 点。’”	voice, notification
conference-callout	向一名或多名参与者拨打语音电话，并将他们连接到共享会议。提示示例：“呼叫 John (+33612345678) 和 Lisa (+34987654321) 并将他们连接到会议室。”	voice
manage-conference-participant	在会议通话中静音、取消静音、保持或恢复单个参与者。提示示例：“将会议中 ID 为 xyz789 的呼叫者静音。”	voice
close-conference	使用会议 ID 断开所有参与者，从而结束会议通话。提示示例：“结束 ID 为 abc123 的当前会议通话。”	voice

号码工具

工具	描述	标签
list-available-regions	列出项目中可提供电话号码的所有区域。可按号码类型（MOBILE, LOCAL, TOLL_FREE）进行过滤。提示示例：“哪些区域有可用的免费电话号码？”	numbers
list-rented-numbers	列出项目中所有活跃（已租用）的电话号码。可按区域、类型、模式和功能进行过滤。提示示例：“向我展示我在美国的所有活跃电话号码。”	numbers
search-for-available-numbers	搜索可供租用的电话号码，支持按区域、类型、模式和功能进行过滤。提示示例：“查找美国支持短信功能的可用本地号码。”	numbers
rent-sinch-virtual-numbers	通过提供 E.164 格式的电话号码来租用（激活）一个或多个电话号码。提示示例：“租用电话号码 +12025551234。”	numbers

配置工具

工具

描述

标签

sinch-mcp-configuration

列出 Sinch MCP 服务器中所有可用的工具及其状态。如果工具被禁用，它将显示原因。

提示示例：“Sinch MCP 服务器中有哪些可用工具？”

Related MCP server: SendGrid MCP Server

入门指南

先决条件

Node.js 20.x 或 22.x (LTS)
一个已配置的 Sinch Build 账户
Claude Desktop（或任何其他 MCP 客户端）。本 README 重点介绍 Claude Desktop，但 MCP 服务器可与任何 MCP 客户端一起使用。

API 凭据

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

会话 / 号码 API 凭据：
- (必需) PROJECT_ID：从您的 Sinch Build 仪表板中选择要使用的项目（位于顶部工具栏左侧）
- (必需) KEY_ID：在 Sinch Build 仪表板的 Access keys 部分中选择或创建新的访问密钥。
- (必需) KEY_SECRET：这是与您在上一步中选择或创建的 Access Key 关联的密钥。请注意，Access Key Secret 仅在创建 Access Key 时显示一次。如果您丢失了它，则需要创建一个新的 Access Key。
- CONVERSATION_APP_ID：这是您要使用的会话应用程序的 ID。您可以在 Sinch Build 仪表板的 Conversation API / Apps 部分中找到它。如果您不设置它，则需要在提示中指定它。
- CONVERSATION_REGION：这是您的会话应用程序和模板所在的区域。可以是 us、eu 或 br。如果您不设置它，默认为 us。
- 使用短信渠道时，您还可以将 DEFAULT_SMS_ORIGINATOR 环境变量设置为将用作短信发送者的电话号码。根据您所在的国家/地区，此设置可能是必需的。
- 如果您想使用位置功能，还可以将 GEOCODING_API_KEY 环境变量设置为您的 Google 地理编码 API 密钥。这是将地址转换为经纬度对所必需的。
验证 API 凭据：导航到 Sinch Build 仪表板的 Verification / Apps 部分并创建新应用或选择现有应用。您将需要以下凭据：
- (必需) APPLICATION_KEY
- (必需) APPLICATION_SECRET
语音 API 凭据：导航到 Sinch Build 仪表板的 Voice / Apps 部分并创建新应用或选择现有应用。您将需要以下凭据：
- (必需) APPLICATION_KEY
- (必需) APPLICATION_SECRET
- 您还可以将 CALLING_LINE_IDENTIFICATION 环境变量设置为用户接听电话时显示的电话号码。
Mailgun API 凭据：导航到 Mailgun 仪表板的 Mailgun / Domains 部分并创建新域名或选择现有域名。您将需要以下凭据：
- (必需) 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": {
        "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": ""
      }
    }
  }
}

在本地运行 MCP 服务器

选项 1：使用 Claude Desktop 通过 stdio 启动 MCP 服务器

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

第 1 步：克隆仓库

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

第 2 步：构建 MCP 服务器

cd sinch-mcp-server
npm install
npm run build

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

第 4 步：（可选）过滤 MCP 服务器中可用的工具

工具太多意味着更大的上下文，意味着更高的 Token 使用量，并且 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 服务器并使用 SSE 连接

使用此选项，您可以在远程机器上运行 MCP 服务器并使用服务器发送事件 (SSE) 连接到它。如果您想在云服务器或专用机器上运行 MCP 服务器，这很有用。默认情况下，Claude Desktop 将使用 STDIO 连接到 MCP 服务器；我们将使用 supergateway 库通过 SSE 连接到 MCP 服务器。

第 1 步：构建 MCP 服务器

cd sinch-mcp-server
npm install
npm run build

第 2 步：设置 MCP 服务器配置

复制 .template.env 文件并将其重命名为 .env。然后用您自己的凭据替换占位符，并删除您不需要的任何键。.env 文件应如下所示 ()：

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

第 3 步：启动 MCP 服务器

npm run start:stdio

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

# 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)"

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

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

第 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 文件中注册。

会话工具：发送各种类型的消息，列出会话应用程序、模板
验证工具：查询号码，执行验证流程
语音工具：拨打 TTS 电话，创建会议通话，管理参与者
电子邮件工具：发送电子邮件，获取电子邮件信息

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

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

Sinch MCP Server