Geotab Ace MCP Demo

Geotab ACE MCP服务器

MCP（模型上下文协议）服务器，为Claude提供与Geotab ACE AI服务交互的工具。此服务器使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  # Optional: for alpha.geotab.com access

多个帐户：

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配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %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.重新启动克劳德桌面

服务器将自动从您的 .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。

示例：“使用以下命令查询缓存的行程数据：SELECT driver_id，COUNT（\*）作为行程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 参数指定要使用的帐户：

Ask Geotab using fleet2: "How many vehicles do we have?"

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

大型数据集的DuckDB缓存

当Ace返回超过200行的数据集时，MCP服务器不会将所有数据发送给Claude：

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

这种方法：

• 防止克劳德被数千行压倒
• 支持强大的基于SQL的分析
• 使复杂查询可以访问完整的数据集
• 无需手动配置即可透明工作

工作流程示例：

User: "Get all trips from last month"
→ Ace returns 10,000 rows
→ Server caches in DuckDB as table 'ace_chat123_msg456'
→ Claude sees: metadata + 20 sample rows + instructions

User: "Show me the top 10 drivers by trip count"
→ Claude queries: SELECT driver_id, COUNT(*) as trips FROM ace_chat123_msg456 GROUP BY driver_id ORDER BY trips DESC LIMIT 10
→ Returns aggregated results instantly

使用模式

简单问题

Ask Geotab: "What's our total mileage for this month?"

复分析

Start a complex Geotab analysis: "Generate a detailed fuel efficiency report for all vehicles, broken down by driver and route, for the past 3 months"

[Wait a few minutes, then:]

Check the status of my Geotab query with chat ID [chat_id] and message group ID [message_group_id]

Get the complete results from chat ID [chat_id] and message group ID [message_group_id]

故障排除

Test my Geotab connection

配置选项

环境变量

单一账户（传统）

多个帐户

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

其中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"

窗户：

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 run python -c "import geotab_ace"
• 确保你已经跑过了 uv sync 安装依赖项

“连接超时”

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

MCP服务器无法启动

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

调试命令

直接测试该实用程序：

# Test connection
uv run python geotab_ace.py --test

# Ask a simple question
uv run python geotab_ace.py --question "How many vehicles do we have?"

# Enable verbose logging
uv run python geotab_ace.py --question "Show me active vehicles" --verbose

测试MCP服务器：

uv run python geotab_mcp_server.py test

文件结构

geotab-mcp-server/
├── geotab_ace.py          # Core API client library
├── geotab_mcp_server.py   # MCP server implementation
├── pyproject.toml         # Project configuration and dependencies
├── .env                   # Your credentials (create this)
└── README.md             # This file

使用uv进行项目设置

此项目使用 uv 用于现代Python依赖管理。以下是如何使用它：

安装uv（如果你还没有）

# macOS (using Homebrew - recommended)
brew install uv

# macOS/Linux (using curl)
curl -LsSf https://astral.sh/uv/install.sh | sh

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

# Or using pip
pip install uv

项目命令

# Install all dependencies
uv sync

# Run the server directly
uv run geotab-mcp-server

# Run with arguments
uv run python geotab_ace.py --test

# Add a new dependency
uv add some-package

# Update dependencies
uv sync --upgrade

API限制和超时

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

依赖项

此项目使用 pyproject.toml 用于依赖性管理。关键依赖关系：

• 意图tp：API调用的异步HTTP客户端
• 熊猫：数据操作和CSV处理
• python dotenv：环境变量加载
• fastmcp：MCP服务器框架

所有依赖项均由自动管理 uv sync.

发展

运行测试

# Test the core library
uv run python geotab_ace.py --test --verbose

# Test the MCP server
uv run python geotab_mcp_server.py test

日志记录

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

export GEOTAB_LOG_LEVEL=DEBUG

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

路线图

看 文档/改进.md 用于计划中的增强功能和未来的功能。我们欢迎对优先事项的贡献和反馈！

支持

对于以下问题：

• Geotab API访问：请联系您的Geotab管理员
• 凭证设置：按照上面的安全部分进行操作
• MCP集成：查看Claude Desktop文档
• 此服务器：检查故障排除部分或查看服务器日志

更多文件

有关为Geotab构建自定义MCP服务器的全面指南，请参阅 自定义MCP指南.

版本信息

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

许可证

此项目根据Apache许可证2.0获得许可-请参阅 许可证 文件以获取详细信息。