shield_lock
金大哥
联系我们
← 返回 MCP 目录
public公开dns本地运行

sinch-mcp-server

Sinch MCP Server是一个开发者预览版工具集，提供与Sinch API交互的多功能服务，包括对话、验证、语音和邮件工具，支持通过Claude Desktop等MCP客户端使用。

article

README

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

本仓库包含 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 | 使用预定义的模板（例如，WhatsApp 或全渠道模板）发送消息。
示例提示：“通过 Messenger 向该用户发送西班牙语的预约提醒模板。” | conversation, notification | | send-choice-message | 发送包含交互式选项（按钮或快速回复）的消息。
示例提示：“向 +33662162504 发送关于首选冰淇淋口味的 RCS 调查，选项如下：香草味、草莓味、榛果味” | conversation, notification | | send-location-message | 向用户发送位置标记或坐标。
示例提示：“向电话号码 +33612345678 发送毕尔巴鄂古根海姆博物馆的位置标记。” | conversation, notification | | get-message-events | 检索与给定消息（文本、媒体、选项等）相关的事件，例如送达状态或阅读回执。
⚠️ 只能检索 MCP 服务器在线期间收到的事件。
示例提示：“消息 01JXYH8RB8MZCAFR117KQAQMQ0 的送达状态如何？” | conversation, notification | | list-all-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-call | 向一个或多个参与者发起语音通话并将他们连接到共享会议。
示例提示：“拨打约翰（+33612345678）和丽莎（+34987654321）的电话并将他们连接到会议室。” | voice | | manage-conference-participant | 静音、取消静音、保持或恢复会议通话中的单个参与者。
示例提示：“静音会议中 ID 为 xyz789 的呼叫者。” | voice | | close-conference | 使用会议 ID 断开所有参与者的连接来结束会议通话。
示例提示：“结束当前 ID 为 abc123 的会议通话。” | voice |

配置工具

| 工具 | 描述 | 标签 | | ---- | ---- | ---- | | sinch-mcp-configuration | 列出 Sinch MCP 服务器中所有可用的工具及其状态。如果某个工具被禁用，它将显示禁用原因。
示例提示：“Sinch MCP 服务器中有哪些可用的工具？” | |

🚀 快速开始

前提条件

API 凭证

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

  • 对话 API 凭证：
    • （必需）CONVERSATION_PROJECT_ID：从 Sinch Build 控制台 中选择您要使用的项目（位于顶部工具栏左侧） 项目 ID 选择
    • （必需）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
  1. 步骤 2：构建 MCP 服务器
cd sinch-mcp-server
npm install
npm run build
  1. 步骤 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": ""
      }
    }
  }
}
  1. 步骤 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
  1. 步骤 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=
  1. 步骤 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)"
  1. 步骤 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
help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端