内容
# Kudosity MCP 服务器
一个可安装的 [模型上下文协议](https://modelcontextprotocol.io) 服务器，为 AI 代理提供原生工具，以发送 **短信、彩信和 WhatsApp** 消息，管理联系人和 webhook，并研究 Kudosity API — 由 [Kudosity](https://kudosity.com) 提供支持。
在本地（或在您自己的基础设施中）运行，使用您的 Kudosity API 密钥进行身份验证，并公开每个操作的一个干净工具 — 因此代理调用 `send_sms` 而不是手动构建 HTTP 请求。
## 工具
**消息**
| 工具 | 类型 | 描述 |
|---|---|---|
| `send_sms` | write | 向收件人发送短信 |
| `send_mms` | write | 发送带有媒体附件的彩信 |
| `send_whatsapp` | write | 发送 WhatsApp 消息（自由格式文本或批准的模板） |
| `get_message` | read | 通过渠道 + ID 获取已发送的消息及其状态 |
| `list_messages` | read | 列出已发送/接收的消息，包含投递状态；按状态、方向（发送/回复）、收件人、日期过滤 |
**Webhook**
| 工具 | 类型 | 描述 |
|---|---|---|
| `create_webhook` | write | 注册一个 HTTPS webhook，用于投递状态、传入消息、链接点击、退出 |
| `list_webhooks` | read | 列出已配置的 webhook |
| `delete_webhook` | write | 删除一个 webhook， 按 ID |
**联系人 & 列表** *(需要 `KUDOSITY_API_SECRET`)*
| 工具 | 类型 | 描述 |
|---|---|---|
| `create_list` | write | 创建一个联系人列表 |
| `get_lists` | read | 列出所有联系人列表 |
| `get_list` | read | 获取一个列表及其成员（可选） |
| `add_contact_to_list` | write | 将联系人添加到列表中 |
| `remove_contact_from_list` | write | 从列表中删除联系人 |
| `delete_list` | write | 删除一个联系人列表 |
**账户** *(需要 `KUDOSITY_API_SECRET`)*
| 工具 | 类型 | 描述 |
|---|---|---|
| `get_balance` | read | 获取您的账户余额 |
**API 发现** — 研究整个 Kudosity API，始终保持最新
| 工具 | 类型 | 描述 |
|---|---|---|
| `list_specs` | read | 列出 Kudosity API 规格 |
| `list_endpoints` | read | 列出某个规格的所有端点 |
| `search_endpoints` | read | 按关键词搜索 API |
| `get_endpoint` | read | 获取一个端点的完整详细信息 |
发现工具从 `developers.kudosity.com` 读取实时规格，因此它们始终反映最新的已发布文档。
## 要求
- Node.js 18+
- 一个 Kudosity 账户和 API 密钥 — **设置 → API 设置** 在 Kudosity 平台上
- 对于联系人和余额工具，还需要您的 API **密钥** （同一设置页面）
## 安装 & 配置
通过 `npx` 运行 — 无需克隆。
### Claude 桌面版 / Claude 代码
```json
{
"mcpServers": {
"kudosity": {
"command": "npx",
"args": ["-y", "kudosity-mcp"],
"env": {
"KUDOSITY_API_KEY": "您的 API 密钥",
"KUDOSITY_API_SECRET": "您的 API 密钥"
}
}
}
}
```
`KUDOSITY_API_SECRET` 是可选的 — 如果您只需要消息、Webhook 和发现，请省略它。它是联系人列表和余额工具所必需的。
### 光标 — `.cursor/mcp.json`
```json
{
"mcpServers": {
"kudosity": {
"command": "npx",
"args": ["-y", "kudosity-mcp"],
"env": { "KUDOSITY_API_KEY": "您的 API 密钥", "KUDOSITY_API_SECRET": "您的 API 密钥" }
}
}
}
```
### VS 代码 — `.vscode/mcp.json`
```json
{
"servers": {
"kudosity": {
"command": "npx",
"args": ["-y", "kudosity-mcp"],
"env": { "KUDOSITY_API_KEY": "您的 API 密钥", "KUDOSITY_API_SECRET": "您的 API 密钥" }
}
}
}
```
## 使用示例
- *"向 61438333061 发送短信，来自 KudosityDemo，说订单已发货。"*
- *"向 61411122211 发送订单状态样本 WhatsApp 模板。"*
- *"列出我昨天发送的短信。"* / *"显示我接收的短信回复。"*
- *"创建一个名为 VIP 的联系人列表，并添加 61438333061。"*
- *"在 https://example.com/hook 注册一个 Webhook，用于短信投递状态。"*
- *"我的账户余额是多少？"*
- *"在 Kudosity API 中搜索有关退出操作的任何信息。"*
## 身份验证
Kudosity 有两个 API 接口，此服务器在每个接口中都使用其授权方式：
| 工具 | 认证 | 凭证 |
|---|---|---|
| 消息、Webhook、发现 | `x-api-key` 头部 | `KUDOSITY_API_KEY` |
| 联系人列表、余额 | HTTP 基本认证 | `KUDOSITY_API_KEY` + `KUDOSITY_API_SECRET` |
凭证从环境变量中读取，绝不会写入磁盘。请像对待密钥一样保护它们。
## 配置
| 环境变量 | 必需 | 默认值 | 描述 |
|---|---|---|---|
| `KUDOSITY_API_KEY` | 是 | — | 您的 Kudosity API 密钥 |
| `KUDOSITY_API_SECRET` | 联系人/余额 | — | 您的 Kudosity API 密钥 |
| `KUDOSITY_API_BASE_URL` | 否 | `https://api.transmitmessage.com` | 覆盖 v2 API 基本 URL |
| `KUDOSITY_V1_BASE_URL` | 否 | `https://api.transmitsms.com` | 覆盖 v1 API 基本 URL |
## 本地开发
```bash
git clone https://github.com/kudosity/mcp
cd mcp
npm install
npm run build
KUDOSITY_API_KEY=您的 API 密钥 npm start
```
使用 MCP 检查器测试工具列表，或运行检查：
```bash
npm test # 模拟集成测试（无凭证）
node test/discovery-test.mjs # 实时规格发现测试（无凭证）
```
## 许可证
[MIT](./LICENSE)
