Ambivo Claude MCP 服务器

此 Claude MCP（模型上下文协议）服务器提供对 Ambivo API 端点的访问，支持通过 Claude AI 对实体数据进行自然语言查询。

功能特性

• 自然语言查询：使用 /entity/natural_query 端点对实体数据执行自然语言查询

• JWT 认证：使用 Bearer 令牌认证确保访问安全

• 速率限制：内置速率限制以防止 API 滥用

• 令牌缓存：高效的令牌验证与缓存

• 错误处理：全面的错误处理，提供详细的错误信息

• 重试机制：对失败的请求自动进行指数退避重试

工具

1. set_auth_token

设置用于 Ambivo API 认证的 JWT Bearer 令牌。

参数：

• token（字符串，必填）：JWT Bearer 令牌

用法：

{
  "token": "your-jwt-token-here"
}

2. natural_query

对 Ambivo 实体数据执行自然语言查询。

参数：

• query（字符串，必填）：描述您所需数据的自然语言查询

• response_format（字符串，可选）：响应格式 - "table"、"natural" 或 "both"（默认："both"）

示例查询：

• "显示我本周创建的线索"

• "查找使用 gmail 地址的联系人"

• "列出价值超过 10,000 美元的商机"

• "显示过去 7 天内 attribution_source 为 google_ads 的线索"

用法：

{
  "query": "Show me leads created this week with attribution_source google_ads",
  "response_format": "both"
}

关于

这是针对 Ambivo API 的纯 Claude 版 MCP 服务器实现，旨在与 Claude Desktop 及其他兼容 Claude 的 MCP 客户端无缝协作。通过 Claude 强大的语言理解能力，实现对 Ambivo CRM 数据的自然语言交互。

安装

方式一：从 PyPI 安装（推荐）

pip install ambivo-mcp-server

方式二：从源码安装

git clone https://github.com/ambivo-corp/ambivo-mcp-server.git
cd ambivo-mcp-server
pip install -e .

运行服务器

# If installed via pip
ambivo-mcp-server

# Or using Python module
python -m ambivo_mcp_server.server

配置

服务器使用以下默认配置：

• 基础 URL：https://goferapi.ambivo.com

• 超时时间：30 秒

• 内容类型：application/json

如有需要，您可以在 AmbivoAPIClient 类中修改这些设置。

认证

1. 首先，使用 set_auth_token 工具设置您的认证令牌

2. 该令牌将作为 Bearer 令牌包含在所有后续 API 请求中

3. 令牌应为来自您的 Ambivo API 认证的有效 JWT 令牌

错误处理

服务器提供全面的错误处理：

• 认证错误：当令牌缺失或无效时提供清晰的提示信息

• HTTP 错误：详细的 HTTP 状态码和响应消息

• 验证错误：参数验证并提供有用的错误消息

• 网络错误：超时和连接错误处理

API 端点

此 MCP 服务器与以下 Ambivo API 端点交互：

/entity/natural_query

• 方法：POST

• 用途：处理用于实体数据检索的自然语言查询

• 认证：必需（JWT Bearer 令牌）

• 内容类型：application/json

/entity/data

• 方法：POST

• 用途：使用结构化参数直接访问实体数据

• 认证：必需（JWT Bearer 令牌）

• 内容类型：application/json

示例工作流程

1. 设置认证：

   {
     "tool": "set_auth_token",
     "arguments": {
       "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
     }
   }

2. 自然语言查询：

   {
     "tool": "natural_query", 
     "arguments": {
       "query": "Show me all leads created in the last 30 days with phone numbers",
       "response_format": "both"
     }
   }

3. 直接实体查询：

   {
     "tool": "entity_data",
     "arguments": {
       "entity_type": "contact",
       "filters": {"email": {"$regex": "@gmail.com$"}},
       "limit": 100,
       "sort": {"created_date": -1}
     }
   }

开发

要扩展此 MCP 服务器：

1. 添加新工具：在 handle_list_tools() 和 handle_call_tool() 函数中实现其他工具

2. 修改 API 客户端：扩展 AmbivoAPIClient 类以支持其他端点

3. 更新配置：修改配置部分中的默认设置

故障排除

常见问题：

1. "需要认证"错误：确保您已先调用 set_auth_token

2. HTTP 401/403 错误：验证您的 JWT 令牌是否有效且未过期

3. 连接超时：检查网络连接和 API 端点可用性

4. 参数无效：查看工具模式以了解必填和可选参数

日志记录：

服务器会记录重要事件和错误。请查看控制台输出以获取调试信息。