Ambivo MCP Server

Ambivo Claude MCP服务器

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

特性

• 自然语言查询：使用以下命令对实体数据执行自然语言查询 /entity/natural_query 端点
• JWT身份验证：使用承载令牌身份验证进行安全访问
• 速率限制：限制内置速率以防止API滥用
• 令牌缓存：通过缓存进行高效的令牌验证
• 错误处理：具有详细错误消息的全面错误处理
• 重试逻辑：对失败的请求进行指数回退的自动重试

工具

1. set_auth_token

设置JWT承载令牌，以便使用Ambivo API进行身份验证。

参数：

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

用途：

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

2. natural_query

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

参数：

• query （字符串，必填）：描述所需数据的自然语言查询
• response_format （字符串，可选）：响应格式-“表”、“自然”或“两者”（默认值：“两者”）

示例查询：

• “显示本周创建的潜在客户”
• “查找具有gmail地址的联系人”
• “列出价值超过10000美元的机会”
• “显示过去7天内带有归因_来源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数据进行自然语言交互。

安装

选项1：从PyPI安装（推荐）

pip install ambivo-mcp-server

选项2：从源代码安装

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. 该令牌将作为承载令牌包含在所有后续API请求中
3. 该令牌应该是来自Ambivo API身份验证的有效JWT令牌

错误处理

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

• 身份验证错误：令牌丢失或无效时清除消息
• HTTP错误：详细的HTTP状态代码和响应消息
• 验证错误：参数验证，并显示有用的错误消息
• 网络错误：超时和连接错误处理

API终点

此MCP服务器与以下Ambivo API端点接口：

/entity/natural_query

• 方法：POST
• 目的：处理实体数据检索的自然语言查询
• 认证：必填（JWT承载令牌）
• 内容类型：应用程序/json

/entity/data

• 方法：POST
• 目的：使用结构化参数直接访问实体数据
• 认证：必填（JWT承载令牌）
• 内容类型：应用程序/json

工作流示例

1. 设置身份验证:

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

1. 自然语言查询:

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

1. 直接实体查询:

   {
     "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. 无效参数：查看工具架构中的必需和可选参数

登录中：

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