Thruai Voice Agent Server

ThruAI MCP Server

ThruAI 语音 Agent 平台的 Model Context Protocol 服务

让 Claude、GPT 等 AI 助手和自定义 Agent 能够通过 Model Context Protocol（MCP）发现并使用 ThruAI 的语音 AI 功能。

**⚡ Beta 版通知：**ThruAI 正在积极开发中。Beta 版期间，默认 API 端点（api.thru.ai）可能需要使用自定义基础 URL。如有需要，请在环境中设置 THRUAI_BASE_URL。申请提前体验 →

功能

• 🚀 快速开始：通过一条命令创建配置完整的语音 Agent 和电话号码
• 🤖 语音 Agent：对 AI 语音 Agent（S2S 或传统管线）进行完整的 CRUD 操作
• 📞 外呼：通过 Agent 向任意电话号码拨打电话
• 📊 分析：提供使用情况和成本分析，并按组件细分
• 📱 电话服务：搜索、配置和分配电话号码
• 🔄 工作流：使用 30 多种节点类型（CRM、日历、电子邮件、表格、网页、社交）构建复杂的自动化流程
• 📢 营销活动：通过自动化联系人管理，大规模拨打外呼电话
• 🔔 Webhook：实时事件通知（call.completed、transcript.ready 等）
• 🛠️ 自定义工具：定义基于 Webhook 的工具，供 Agent 在实时对话中调用
• 🎤 服务商发现：列出可用的 LLM/TTS/STT 服务商、语音和模型
• 💬 反馈：提交错误报告和功能请求
• 🔍 Schema 发现：获取准确的 API schema，避免字段名称拼写错误
• 📦 50 多种工具：全面覆盖整个 ThruAI 平台
• 🎯 面向 AI 优先设计：专为 AI Agent 集成而打造

安装

选项 1：通过 npx 使用（推荐）

无需安装，直接通过 npx 运行：

THRUAI_API_KEY=sk_live_... npx github:mgWellPay/thruai-mcp-server

选项 2：全局安装

npm install -g github:mgWellPay/thruai-mcp-server
THRUAI_API_KEY=sk_live_... thruai-mcp

选项 3：本地安装

npm install github:mgWellPay/thruai-mcp-server

快速开始

1. 获取 API 密钥

1. 在 thru.ai 注册
2. 前往 Settings → API Keys
3. 创建一个新的 API 密钥（以 sk_live_ 开头）

2. 使用 Claude Code 进行配置

添加到 Claude Code 配置文件（~/.config/claude-code/config.json）：

{
  "mcpServers": {
    "thruai": {
      "command": "npx",
      "args": ["github:mgWellPay/thruai-mcp-server"],
      "env": {
        "THRUAI_API_KEY": "sk_live_...",
        "THRUAI_BASE_URL": "https://api.thru.ai"
      }
    }
  }
}

3. 在 Claude 中开始使用 ThruAI 工具

User: Create a voice agent that answers customer support questions

Claude: I'll use the quickstart tool to create a fully configured agent with a phone number:

<uses quickstart tool>
{
  "name": "Support Agent",
  "systemPrompt": "You are a helpful customer support agent. Answer questions about our products and help resolve issues.",
  "areaCode": "415"
}

✅ Success! Agent "Support Agent" is ready!

Phone: +1 (415) 555-1234
Agent ID: AGT-abc123

You can now:
• Call +1 (415) 555-1234 to test the agent
• Make outbound calls with make_call tool
• View call history with list_calls tool

可用工具（50 多种）

ThruAI MCP 服务通过 50 多种工具，按领域提供整个平台的完整功能：

🚀 快速开始

quickstart

通过一次调用创建 Agent 和电话号码（推荐）

通过一条命令创建配置完整的语音 Agent 和电话号码。这是最快的入门方式。

{
  name: string;           // Agent name
  systemPrompt?: string;  // AI instructions
  areaCode?: string;      // Default: "415"
  voice?: string;         // Default: "alloy"
  model?: string;         // Default: "gpt-realtime"
}

示例：

Use quickstart with:
- name: "Sales Agent"
- systemPrompt: "You are a sales agent for Acme Corp. Qualify leads and book demos."
- areaCode: "212"

---

🤖 Agent 管理（6 种工具）

create_agent

使用智能默认设置创建语音 Agent。建议使用 S2S 管线以获得最低延迟。

get_agent

获取 Agent 的详细配置和状态。

update_agent

更新 Agent 名称、系统提示词、语音或其他设置。

delete_agent

永久删除 Agent。

list_agents

分页列出所有 Agent。

示例：

{
  page?: number;      // Default: 1
  pageSize?: number;  // Default: 50
}

---

📞 通话（3 种工具）

make_call

通过 Agent 向任意电话号码拨打外呼电话。

{
  agentId: string;  // AGT-xxxxx
  to: string;       // E.164 format: "+14155551234"
  from?: string;    // Optional: specific number to call from
}

list_calls

根据 Agent、状态和日期范围筛选并列出近期通话。

get_call

获取完整的通话详情，包括转录文本、时长、成本和 AI 洞察。

---

📱 电话服务（3 种工具）

search_numbers

按区号和国家/地区搜索可用电话号码。

{
  areaCode?: string;  // e.g., "415", "212"
  country?: string;   // Default: "US"
  limit?: number;     // Default: 10
}

provision_number

购买电话号码。

assign_number

将电话号码分配给 Agent，以便拨打呼入和呼出电话。

---

🔄 工作流（9 种工具）

使用 30 多种节点类型构建复杂的自动化流程：CRM、日历、电子邮件、表格、网页、社交和逻辑。

create_workflow

创建包含节点和边的新工作流。

get_workflow

获取工作流详情，包括完整的 DAG 定义。

update_workflow

更新工作流配置或逻辑。

delete_workflow

删除工作流。

publish_workflow

发布工作流，使其可以执行。

unpublish_workflow

取消发布工作流，以便在进行更改时阻止执行。

trigger_workflow

手动触发工作流执行。

list_workflows

列出所有工作流。

list_workflow_executions

查看执行历史记录，包括状态和错误。

---

📢 营销活动（8 个工具）

通过自动化联系人管理，大规模进行外呼。

create_campaign

创建新的外呼营销活动。

get_campaign

获取营销活动详情和配置。

update_campaign

更新营销活动设置。

delete_campaign

删除营销活动。

start_campaign

开始呼叫营销活动中的联系人。

pause_campaign

暂停正在进行的营销活动。

add_campaign_contacts

添加联系人及其电话号码和元数据。

{
  campaignId: string;
  contacts: Array<{
    phoneNumber: string;
    name?: string;
    customData?: Record<string, unknown>;
  }>;
}

get_campaign_stats

获取实时统计数据：排队中、进行中、已完成、失败和成功率。

list_campaigns

列出所有营销活动，并支持按状态筛选。

---

🔔 Webhook（6 个工具）

针对 call.completed、transcript.ready、workflow.completed 等事件发送实时通知。

create_webhook

订阅事件并验证 HMAC 签名。

{
  url: string;  // HTTPS endpoint
  events: string[];  // ["call.completed", "transcript.ready"]
  secret?: string;  // For HMAC verification
}

get_webhook

获取 Webhook 详情。

update_webhook

更新 URL、事件或启用状态。

delete_webhook

删除 Webhook 订阅。

test_webhook

发送测试事件以验证配置。

list_webhook_deliveries

查看投递尝试记录，包括状态码和错误。

list_webhooks

列出所有 Webhook 订阅。

---

🛠️ 自定义工具（6 个工具）

定义基于 Webhook 的工具，供 Agent 在实时对话中调用。

create_tool

创建 Agent 可实时调用的自定义工具。

{
  name: string;  // Tool name for agent invocation
  description?: string;
  url: string;  // HTTPS endpoint
  parameters?: Record<string, unknown>;  // JSON schema
  timeout?: number;  // 1-30 seconds
}

get_tool

获取工具详情和配置。

update_tool

更新工具 URL、参数或超时时间。

delete_tool

删除工具（如果有 Agent 引用了该工具，会发出警告）。

test_tool

使用示例载荷测试工具。

list_tools

列出所有自定义工具。

---

📊 分析（2 个工具）

按组件细分的使用情况和成本分析。

get_usage_analytics

获取通话量、时长和转录使用情况。

{
  startDate?: string;  // ISO 8601
  endDate?: string;
  granularity?: 'day' | 'week' | 'month';
}

get_cost_analytics

获取成本细分数据，包括 LLM、TTS、STT 和电话服务。

---

🎤 提供商（3 个工具）

查找可用的 LLM、TTS 和 STT 提供商。

list_providers

按类型（llm、tts、stt）分组列出所有提供商。

list_voices

列出 TTS 提供商（ElevenLabs、Cartesia、Google）的语音。

list_models

列出 LLM 或 STT 提供商（OpenAI、Anthropic、Groq）的模型。

---

💬 反馈（3 个工具）

提交并跟踪 Bug 报告、功能请求和一般反馈。

submit_feedback

向 ThruAI 团队提交反馈。

{
  type: 'bug' | 'feature' | 'general';
  subject: string;
  description: string;
  priority?: 'low' | 'medium' | 'high';
}

get_feedback

获取反馈详情。

list_feedback

列出所有反馈提交记录。

---

🔍 架构发现（1 个工具）

get_schemas

发现准确的 API 架构，避免字段名称拼写错误。返回所有端点的 Zod 架构。

配置

环境变量

• THRUAI_API_KEY（必填）：你的 ThruAI API 密钥，可从 https://thru.ai/settings/api-keys 获取
• THRUAI_BASE_URL（可选）：API 基础 URL（默认值：https://api.thru.ai）

Claude Code 配置

~/.config/claude-code/config.json：

{
  "mcpServers": {
    "thruai": {
      "command": "npx",
      "args": ["github:mgWellPay/thruai-mcp-server"],
      "env": {
        "THRUAI_API_KEY": "sk_live_your_key_here",
        "THRUAI_BASE_URL": "https://api.thru.ai"
      }
    }
  }
}

Claude Desktop 配置

~/Library/Application Support/Claude/claude_desktop_config.json（macOS） %APPDATA%/Claude/claude_desktop_config.json（Windows）

{
  "mcpServers": {
    "thruai": {
      "command": "npx",
      "args": ["github:mgWellPay/thruai-mcp-server"],
      "env": {
        "THRUAI_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

使用示例

示例 1：创建客户支持 Agent

User: Create a customer support agent for my SaaS company

Claude: I'll create a fully configured support agent with quickstart:

<uses quickstart>
{
  "name": "SaaS Support Agent",
  "systemPrompt": "You are a helpful customer support agent for [Company]. Help users with: account issues, billing questions, feature explanations, and bug reports. Always be friendly and professional. If you can't solve an issue, offer to escalate to a human agent.",
  "areaCode": "650"
}

✅ Agent ready! Phone: +1 (650) 555-7890

示例 2：拨打外呼销售电话

User: Call this lead list and qualify them
[+14155551234, +14155552345, +14155553456]

Claude: I'll make outbound calls to each lead:

<uses make_call for each number>

Initiated 3 calls:
1. +14155551234 - Call ID: CALL-abc
2. +14155552345 - Call ID: CALL-def
3. +14155553456 - Call ID: CALL-ghi

I can check the results with list_calls or get_call once they complete.

示例 3：分析通话转录文本

User: Show me the transcripts from yesterday's calls

Claude: <uses list_calls with date filter>

Found 12 completed calls. Here are the highlights:

Call CALL-abc123 (8 min, $0.12):
- Lead: Interested in Enterprise plan
- Next step: Send pricing proposal
- Sentiment: Positive

<uses get_call to fetch full transcripts for analysis>

MCP 资源

MCP 资源是只读数据源，AI Agent 可通过查询它们了解当前状态。ThruAI MCP 服务提供：

• thruai://agents - 所有语音 Agent 的列表
• thruai://workflows - 所有工作流的列表
• thruai://campaigns - 所有营销活动的列表
• thruai://webhooks - Webhook 订阅列表
• thruai://tools - 自定义工具列表
• thruai://providers - 可用的大模型／TTS／STT 提供商及其模型和语音
• thruai://calls/recent - 最近的通话记录

AI Agent 访问资源时，资源会自动刷新。

在 Claude 中使用：

User: Show me all my agents
Claude: <reads thruai://agents resource>
You have 3 agents:
1. Support Agent (AGT-abc123) - Active
2. Sales Agent (AGT-def456) - Active
3. Demo Agent (AGT-ghi789) - Draft

---

架构

此 MCP 服务使用 ThruAI 的公开 REST API 来：

1. 进行身份验证：使用你的 API 密钥（Bearer 令牌）
2. 创建资源：Agent、电话号码、工作流、营销活动
3. 发起通话：通过电话 API 发起外呼
4. 检索数据：通话日志、转录文本、分析数据、执行历史记录
5. 管理 Webhook：订阅实时事件
6. 定义工具：用于实时对话的自定义 Webhook 工具

所有请求都通过 https://api.thru.ai/api/v1/public/ 发送。

---

即将推出的功能

以下功能正在开发中，近期将添加到公开 API：

🧠 学习系统（即将推出）

• get_agent_analytics：性能指标、情绪、解决率
• get_recommendations：AI 生成的提示词改进建议
• create_experiment：对 Agent 配置进行 A/B 测试

📚 知识库（即将推出）

• crawl_website：根据网站内容构建知识库
• query_knowledge：在通话过程中使用 RAG（检索增强生成）

这些功能目前仅供内部使用，未来更新后将通过公开 API 提供。

语音 Agent 说明

ThruAI 语音 Agent 是由 AI 驱动的系统，可以：

• 接听电话：接听分配的电话号码上的来电
• 拨打电话：向任意电话号码发起外呼
• 自然对话：使用先进的语音到语音 AI（延迟为 200-400 毫秒）
• 遵循指令：通过系统提示词配置（类似 ChatGPT）
• 执行操作：通过工作流与 CRM、日历、数据库集成

管线模式

S2S（语音到语音）——推荐：

• 单个模型一步完成语音到语音处理
• 超快：端到端延迟为 200-400 毫秒
• OpenAI Realtime API（gpt-4o-realtime）
• 10 种语音：alloy、ash、ballad、coral、echo、sage、shimmer、verse

传统模式（STT → LLM → TTS）：

• 分为三个步骤：语音转文本 → 大模型 → 文本转语音
• 较慢：延迟为 800-1200 毫秒
• 更灵活：可混用不同提供商（ElevenLabs 语音 + Claude 大模型）
• 仅在需要使用 S2S 不提供的特定语音时使用

故障排除

“身份验证失败”

检查你的 API 密钥：

• 以 sk_live_ 或 sk_test_ 开头
• 从 https://thru.ai/settings/api-keys 获取
• 设置在 THRUAI_API_KEY 环境变量中

“电话配置失败”

常见原因：

1. 未设置付款方式：通过 https://thru.ai/settings/billing 添加
2. 区号不可用：使用 search_numbers 尝试其他区号
3. 已达到号码上限：升级套餐或联系支持团队

“未找到 Agent”

请确保：

• Agent ID 格式正确：AGT-xxxxx
• Agent 属于你的组织
• 使用 list_agents 查看可用 Agent

Claude 中未显示 MCP 服务

1. 检查配置文件的位置和语法
2. 重启 Claude Code/Desktop
3. 检查 stderr 输出：npx github:mgWellPay/thruai-mcp-server 2>&1 | tee mcp.log
4. 确认 API 密钥有效

支持

• 文档：https://thru.ai/docs
• API 参考：https://api.thru.ai/api/v1/public/
• 问题反馈：https://github.com/thruai/thruai-mcp-server/issues
• 电子邮件：[email protected]

许可证

MIT 许可证——详情请参阅 LICENSE 文件

Links

• ThruAI Platform: https://thru.ai
• API Documentation: https://thru.ai/docs/api
• MCP Specification: https://modelcontextprotocol.io
• Claude Code: https://claude.ai/code