AI导哈

Telnyx AI MCP集成服务

一个通过FastAPI实现的MCP服务器，提供创建潜在客户（Postgres）、安排会议（Google Calendar）和发送电子邮件（Gmail）的功能，适用于客户关系管理和自动化工作流。

  • by Soab42
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 Soab42/mcp-server

使用说明

Telnyx AI → MCP（fastmcp）→ Google + PostgreSQL

这个项目为你提供：

  • 一个MCP服务器，提供工具用于创建潜在客户（使用PostgreSQL）、安排会议（使用Google日历）以及发送电子邮件（使用Gmail）。
  • 一个 FastAPI 网络钩子（POST /webhooks/telnyx-ai) 该系统对Telnyx AI呼叫事件进行端到端处理。

建筑学

Telnyx AI → (Webhook) FastAPI →

  1. Postgres：插入领先（或“插入先导”）
  2. Google 日历：创建活动（可选）
  3. Gmail：发送确认（可选）

所有这3个操作也可以通过MCP工具来执行 fastmcp。

文件结构

  • main.py应用程序的主要入口点。它初始化FastAPI和FastMCP服务器，并注册webhook和MCP工具。
  • db.py处理数据库连接和操作。
  • google_client.py管理与Google日历和Gmail API的交互。
  • mcp_tools.py包含所有MCP工具的定义。
  • telnyx_handler.py处理传入的Telnyx AI Webhook。
  • models.py定义了Telnyx AI Webhook有效载荷的Pydantic模型。

先决条件

  • Python 3.11或更高版本
  • Postgres 数据库
  • 推荐使用Google Workspace（带有域名范围委托的服务账户）
  • Telnyx AI助手已配置为调用您的公共Webhook URL

快速入门

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
export DATABASE_URL="postgresql+psycopg2://user:pass@host:5432/db"
export GOOGLE_SERVICE_ACCOUNT_INFO='{"type": "service_account", ... }'
export GOOGLE_IMPERSONATE_SUBJECT="support@businessvoicepro.com"
export GMAIL_SENDER="support@businessvoicepro.com"
export CALLER_INFO_DATABASE_URL="postgresql+psycopg2://user:pass@host:5432/caller_db"
uvicorn main:app --host 0.0.0.0 --port 8080

您的Webhook终端点现已 https://<your-domain-or-ip>:8080/webhooks/telnyx-ai。

没有服务账户

放置 credentials.json （OAuth客户端）在应用程序旁边，运行一次本地认证流程以生成 token.json然后部署两者。设置：

export GOOGLE_CLIENT_SECRET_PATH=credentials.json
export GOOGLE_TOKEN_PATH=token.json
export GMAIL_SENDER=support@businessvoicepro.com

Telnyx AI Webhook 有效载荷（示例）

{
  "call_id": "abc123",
  "caller_number": "+15551234567",
  "caller_name": "Alex Buyer",
  "caller_email": "alex@example.com",
  "transcript": "I want to book a showing next Tuesday at 3pm",
  "meeting_summary": "Buyer Consultation",
  "meeting_description": "Inbound from IVR",
  "meeting_start_iso": "2025-10-14T15:00:00Z",
  "meeting_duration_min": 30,
  "attendees": ["agent@yourbrokerage.com"]
}

MCP 工具

  • mcp_create_lead(name, phone, email, notes) → {status, lead_id}
  • mcp_schedule_meeting(summary, description, start_iso, end_iso, attendees, calendar_id) → {status, event}
  • mcp_send_email(to, subject, body_text, reply_to) → {status}
  • mcp_process_telnyx_payload(payload_json) → 端到端处理。
  • mcp_check_calendar(start_iso, end_iso, calendar_id) → {status, message}
  • mcp_get_caller_info(phone_number) → {status, caller_info}

MCP 检查器

要检查和测试可用的MCP工具，请运行以下命令：

uv run fastmcp dev main.py

MCP演示数据

处理Telnyx有效载荷的MCP进程

{
  "payload_json": "{\"call_id\": \"xyz789\", \"caller_number\": \"+15559876543\", \"caller_name\": \"Dana Developer\", \"caller_email\": \"dana@example.com\", \"transcript\": \"Hi, I'd like to check if there is a meeting slot available next Wednesday at 10am.\", \"meeting_summary\": \"Availability Check\", \"meeting_description\": \"Checking for an open slot.\", \"meeting_start_iso\": \"2025-10-22T10:00:00Z\", \"meeting_duration_min\": 15, \"attendees\": [\"agent@yourbrokerage.com\"]}"
}

创建潜在客户（MCP_Create_Lead）

{
  "name": "John Doe",
  "phone": "+15551112222",
  "email": "john.doe@example.com",
  "notes": "Interested in a demo."
}

安排MCP会议

{
  "summary": "Project Kick-off",
  "description": "Initial meeting to discuss project goals.",
  "start_iso": "2025-11-01T14:00:00Z",
  "end_iso": "2025-11-01T15:00:00Z",
  "attendees": ["jane.doe@example.com", "john.doe@example.com"]
}

发送电子邮件（MCP相关）

{
  "to": ["recipient@example.com"],
  "subject": "Hello from MCP",
  "body_text": "This is a test email from the MCP server."
}

mcp_check_calendar 可以翻译为“MCP检查日历”或“MCP校验日历”，具体取决于上下文中的“MCP”是指什么（可能是某个特定系统、模块或功能的缩写）。在这里，“mcp”可能代表某个特定的模块或系统名称，“check”或“校验”表示对日历进行检查或验证，“calendar”则指的是日历本身

{
  "start_iso": "2025-10-29T10:00:00Z",
  "end_iso": "2025-10-29T11:00:00Z"
}

MCP工具调用日志

MCP工具的调用被记录到数据库中 mcp_tool_logs 表格。您可以导航至（相应位置）查看这些日志的实时流 /logs-ui 在您的网络浏览器中设置终端点。

数据库

首次运行时，该表 leads 自动创建。自定义模式在 db.py。

部署说明

  • **VPS（Virtual Private Server）**在 NGINX 后面运行，使用 HTTPS（由 Let’s Encrypt 提供证书）。systemd 单元文件示例：
[Unit]
Description=Telnyx MCP API
After=network.target

[Service]
User=ubuntu
WorkingDirectory=/opt/telnyx-mcp
Environment="DATABASE_URL=postgresql+psycopg2://..."
Environment="GOOGLE_SERVICE_ACCOUNT_INFO=..."
Environment="GOOGLE_IMPERSONATE_SUBJECT=support@businessvoicepro.com"
Environment="GMAIL_SENDER=support@businessvoicepro.com"
ExecStart=/opt/telnyx-mcp/.venv/bin/uvicorn main:app --host 0.0.0.0 --port 8080
Restart=always

[Install]
WantedBy=multi-user.target
  • 安全添加一个Telnyx签名密钥，并对传入请求验证HMAC；限制CORS（跨域资源共享）；将密钥存储在密钥库中。

Telnyx 签名验证（伪）

验证 Telnyx-Signature-Ed25519 头部信息。请参阅Telnyx文档，并在处理前添加验证。

故障排除

  • Google clients not configured → 确保存在服务帐户变量或OAuth文件。
  • Gmail发送时出现403错误 → 您的工作区管理员必须启用全局委托权限，或者使用具有发送权限的OAuth用户令牌。

相关 MCP