星战科技xingzhan.cloud
返回市场
地理标签Ace MCP演示

地理标签Ace MCP演示

作者：fhoffa5 星标更新：2025-11-22
安装使用来源：spider==github.com

项目介绍

Geotab ACE MCP Server

这是一个提供给Claude与Geotab ACE AI服务交互工具的MCP（模型上下文协议）服务器。此服务器使Claude能够询问车队数据并获取结构化的响应，包括数据集。

注意：这是由Geotab的Felipe Hoffa（https://www.linkedin.com/in/hoffa）发起的一个实验性项目。没有官方支持，但我们欢迎您通过GitHub问题反馈。

功能

  • 多账户支持：同时连接多个Geotab数据库
  • 自动认证：透明处理Geotab API认证
  • 异步查询支持：启动长时间运行的查询并检查其进度
  • 完整数据集检索：下载完整的数据集（当可用时）
  • DuckDB集成：大型数据集（>200行）会自动缓存到DuckDB中进行SQL分析
  • SQL查询接口：使用SQL查询缓存的数据集，而不是检索数千行数据
  • 多种查询工作流：同步和异步查询模式
  • 调试工具：内置调试功能以解决查询问题
  • 安全凭证管理：使用环境变量存储凭证

快速开始

1. 安装依赖项

uv sync

2. 设置凭证

在项目目录中创建一个.env文件：

单个账户：

GEOTAB_API_USERNAME=your_username
GEOTAB_API_PASSWORD=your_password
GEOTAB_API_DATABASE=your_database_name
# GEOTAB_API_URL=https://alpha.geotab.com/apiv1  # 可选：用于访问alpha.geotab.com

多个账户：

GEOTAB_ACCOUNT_1_NAME=fleet1
GEOTAB_ACCOUNT_1_USERNAME=user1@example.com
GEOTAB_ACCOUNT_1_PASSWORD=secret1
GEOTAB_ACCOUNT_1_DATABASE=db1

GEOTAB_ACCOUNT_2_NAME=fleet2
GEOTAB_ACCOUNT_2_USERNAME=user2@example.com
GEOTAB_ACCOUNT_2_PASSWORD=secret2
GEOTAB_ACCOUNT_2_DATABASE=db2

3. 测试连接

uv run python geotab_ace.py --test

4. 配置Claude Desktop

添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "geotab": {
      "command": "uv",
      "args": ["run", "python", "/absolute/path/to/geotab_mcp_server.py"]
    }
  }
}

或者使用已安装的脚本：

{
  "mcpServers": {
    "geotab": {
      "command": "uv",
      "args": ["run", "geotab-mcp-server"],
      "cwd": "/absolute/path/to/project"
    }
  }
}

5. 重启Claude Desktop

服务器将自动从您的.env文件加载凭证。

可用工具

geotab_ask_question

提问并等待完整的响应（默认最多60秒）。

示例："上周有多少辆车是活跃的？"

geotab_start_query_async

启动可能需要几分钟才能处理的复杂查询。立即返回跟踪ID。

用途：复杂分析、大量数据导出、多步骤分析

geotab_check_status

使用跟踪ID检查异步查询的进度。

geotab_get_results

从已完成的查询中检索完整结果，包括完整数据集。

geotab_test_connection

测试API连接性和认证——对于故障排除很有用。

geotab_debug_query

获取关于查询响应结构的详细调试信息。

geotab_query_duckdb

在缓存在DuckDB中的大型数据集上执行SQL查询。当Ace返回超过200行的数据时，数据会被自动加载到DuckDB中，而不是发送给Claude。

示例："使用以下SQL查询缓存的行程数据：SELECT driver_id, COUNT(*) as trips FROM ace_123_456 GROUP BY driver_id ORDER BY trips DESC LIMIT 10"

geotab_list_cached_datasets

列出当前缓存在DuckDB中的所有数据集及其元数据，包括行数、列名和表名。

示例："显示缓存在DuckDB中的数据集"

geotab_list_accounts

列出所有已配置的Geotab账户。显示哪些账户可用以及哪个是默认账户。

示例："列出我的Geotab账户"

多账户使用

所有查询工具接受一个可选的account参数来指定要使用的账户：

使用fleet2账户提问Geotab："我们有多少辆车？"

如果未指定账户，则使用默认账户（多账户设置中的第一个账户，或单账户设置中的“默认”账户）。

DuckDB缓存大型数据集

当Ace返回包含超过200行的数据集时，而不是将所有这些数据发送给Claude，MCP服务器：

  1. 自动加载数据到内存中的DuckDB数据库
  2. 返回元数据，包括行数、列名、数据类型和20行样本
  3. 提供表名用于查询缓存的数据
  4. 提供SQL能力以高效地分析数据

这种方法：

  • 防止Claude被数千行数据淹没
  • 允许强大的基于SQL的分析
  • 保持完整数据集对复杂查询的可访问性
  • 透明地工作，无需手动配置

示例工作流程：

用户："获取上个月的所有行程"
→ Ace返回10,000行
→ 服务器将其缓存到DuckDB作为表'ace_chat123_msg456'
→ Claude看到：元数据+20行样本+操作说明

用户："按行程次数显示前10位司机"
→ Claude查询：SELECT driver_id, COUNT(*) as trips FROM ace_chat123_msg456 GROUP BY driver_id ORDER BY trips DESC LIMIT 10
→ 立即返回聚合结果

使用模式

简单问题

提问Geotab："这个月我们的总里程是多少？"

复杂分析

启动复杂的Geotab分析："生成过去三个月内所有车辆的详细燃油效率报告，按司机和路线细分"

[等待几分钟后：]

检查聊天ID [chat_id] 和消息组ID [message_group_id] 的Geotab查询状态

从聊天ID [chat_id] 和消息组ID [message_group_id] 获取完整结果

故障排除

测试我的Geotab连接

配置选项

环境变量

单个账户（旧版）

变量描述是否必需
GEOTAB_API_USERNAME您的Geotab用户名是
GEOTAB_API_PASSWORD您的Geotab密码是
GEOTAB_API_DATABASE您的Geotab数据库名称是
GEOTAB_API_URLGeotab API端点URL（默认：https://my.geotab.com/apiv1）否
GEOTAB_DRIVER_PRIVACY_MODE在结果中屏蔽司机姓名（默认：true）否

多个账户

为每个账户使用编号的环境变量：

变量描述是否必需
GEOTAB_ACCOUNT_N_NAME账户的友好名称（例如，“fleet1”）是
GEOTAB_ACCOUNT_N_USERNAME账户N的Geotab用户名是
GEOTAB_ACCOUNT_N_PASSWORD账户N的Geotab密码是
GEOTAB_ACCOUNT_N_DATABASE账户N的Geotab数据库名称是

其中N是1, 2, 3等。第一个账户（N=1）成为默认账户。

驾驶员隐私保护模式

默认情况下，服务器会自动从查询结果中屏蔽驾驶员姓名信息，以保护隐私。启用后，任何名为DisplayName、Display Name、LastName、Last Name、FirstName或First Name的列都将被替换为*。

要禁用此功能：

GEOTAB_DRIVER_PRIVACY_MODE=false

该功能默认启用，并在预览和完整数据集下载中屏蔽驾驶员姓名。

重要限制：此功能旨在防止意外泄露驾驶员姓名。它不是安全边界，无法阻止：

  • 恶意提示要求AI在返回数据前重命名列
  • 通过其他列名或其他方法提取驾驶员信息的查询
  • 故意尝试规避屏蔽的行为

为了真正保护数据，应在Geotab API或数据库级别实施适当访问控制。此功能为意外泄露提供了有用的保护网，而非安全保证。

替代方案：系统环境变量

您可以设置系统环境变量，而不是使用.env文件：

macOS/Linux：

export GEOTAB_API_USERNAME="your_username"
export GEOTAB_API_PASSWORD="your_password"
export GEOTAB_API_DATABASE="your_database"

Windows：

setx GEOTAB_API_USERNAME "your_username"
setx GEOTAB_API_PASSWORD "your_password"
setx GEOTAB_API_DATABASE "your_database"

安全考虑

凭证如何处理

  1. 仅本地：凭证仅在Claude Desktop和MCP服务器之间本地使用
  2. 永不传输：您的凭证永远不会发送到Anthropic的服务器
  3. 进程隔离：MCP服务器作为一个独立进程运行，有自己的内存空间
  4. 会话管理：身份验证令牌为提高效率而缓存，但会自动过期

最佳实践

  • 使用具有最小必要权限的专用API账户
  • 定期轮换凭证
  • 对您的.env文件设置严格的文件权限：chmod 600 .env
  • 通过您的Geotab账户监控API使用情况
  • 在首次使用前使用测试连接工具验证设置

故障排除

常见问题

"认证失败"

  • 验证.env文件中的凭证是否正确
  • 检查您的Geotab账户是否有API访问权限
  • 确保数据库名称完全匹配（区分大小写）

"未找到模块'geotab_ace'"

  • 确保两个文件在同一目录下
  • 如果使用uv，尝试：uv run python -c "import geotab_ace"
  • 确保您已经运行了uv sync以安装依赖项

"连接超时"

  • 检查您的互联网连接
  • 验证Geotab服务是否正常运行
  • 尝试增加超时值

MCP服务器无法启动

  • 运行uv run python geotab_mcp_server.py test以诊断问题
  • 查看Claude Desktop日志中的错误消息
  • 验证配置文件中的路径是否正确且使用正斜杠

调试命令

直接测试工具：

# 测试连接
uv run python geotab_ace.py --test

# 提问简单问题
uv run python geotab_ace.py --question "我们有多少辆车？"

# 启用详细日志
uv run python geotab_ace.py --question "显示活跃车辆" --verbose

测试MCP服务器：

uv run python geotab_mcp_server.py test

文件结构

geotab-mcp-server/
├── geotab_ace.py          # 核心API客户端库
├── geotab_mcp_server.py   # MCP服务器实现
├── pyproject.toml         # 项目配置和依赖项
├── .env                   # 您的凭证（创建此文件）
└── README.md             # 此文件

项目设置与uv

此项目使用uv进行现代Python依赖管理。以下是使用方法：

安装uv（如果您还没有安装）

# macOS（使用Homebrew - 推荐）
brew install uv

# macOS/Linux（使用curl）
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# 或者使用pip
pip install uv

项目命令

# 安装所有依赖项
uv sync

# 直接运行服务器
uv run geotab-mcp-server

# 带参数运行
uv run python geotab_ace.py --test

# 添加新依赖项
uv add some-package

# 更新依赖项
uv sync --upgrade

API限制和超时

  • 默认问题超时：60秒
  • 异步查询超时：300秒（5分钟）
  • 会话缓存：1小时
  • 连接超时：60秒
  • 轮询间隔：从2秒开始，逐步增加

依赖项

此项目使用pyproject.toml进行依赖管理。关键依赖项：

  • aiohttp：用于API调用的异步HTTP客户端
  • pandas：数据操作和CSV处理
  • python-dotenv：环境变量加载
  • fastmcp：MCP服务器框架

所有依赖项都由uv sync自动管理。

开发

运行测试

# 测试核心库
uv run python geotab_ace.py --test --verbose

# 测试MCP服务器
uv run python geotab_mcp_server.py test

日志记录

通过设置日志级别启用详细日志：

export GEOTAB_LOG_LEVEL=DEBUG

或者修改代码中的日志配置。

发展路线图

查看docs/improvements.md了解计划改进和未来功能。我们欢迎贡献和反馈！

支持

对于以下问题：

  • Geotab API访问：联系您的Geotab管理员
  • 凭证设置：遵循上述的安全部分
  • MCP集成：查阅Claude Desktop文档
  • 此服务器：查阅故障排除部分或审查服务器日志

版本信息

  • API版本：使用Geotab API v1
  • MCP协议：兼容Claude Desktop MCP实现
  • Python：需要Python 3.7+