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