AI导哈

交通模式分析服务

一个基于Google Maps API的模型上下文协议(MCP)服务器，用于分析24小时内的交通模式，提供快速可视化洞察和智能通勤建议。

  • by 100shpaik
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 100shpaik/mcp-gmap-time

使用说明

驱动时间绘图仪MCP

模型上下文协议（MCP）服务器，使用谷歌地图API分析全天的交通模式，提供快速的视觉见解和建议。

受到激励 拥抱面孔MCP黑客马拉松 -用于智能通勤规划的生产就绪MCP服务器。

它做什么

  • 以15分钟为间隔分析24小时内的交通模式
  • 显示乐观/悲观/平均驾驶时间预测
  • 使用并行API请求在约4秒内完成完整分析（比顺序请求快120倍！）
  • 可与Claude Desktop、Claude Code和独立CLI配合使用
  • 生成终端ASCII图和路线图

快速开始

1.安装

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .

2.设置API密钥

从获取您的Google Maps API密钥https://console.cloud.google.com/apis/credentials

启用这些API：

  • 地理编码API
  • API指南
  • 映射静态API

创建 .env 模板中的文件：

cp .env.example .env
# Edit .env and add your key:
# GOOGLE_MAPS_API_KEY=your_key_here

3.测试

./test.sh

您应该在大约4秒后看到流量分析！

用法

终端（最快）

./test_custom.sh

编辑 test_custom.sh 自定义：

  • 起点/终点（默认：加州大学伯克利分校埃文斯厅→ SFO)
  • 日期
  • 时间范围
  • 间隔

或者直接使用CLI：

python cli/driveplot_fast.py \
  --origin "Your Home" \
  --destination "Your Work" \
  --date 2025-11-20 \
  --start 06:00 --end 10:00 \
  --interval 15 \
  --ascii --save-map outputs/route.png --yes

使用Claude作为MCP服务器

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "drivetime-plotter": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "env": {
        "GOOGLE_MAPS_API_KEY": "your_key_here"
      },
      "cwd": "/path/to/mcp-hackathon"
    }
  }
}

重新启动克劳德桌面。你现在可以问克劳德：“我什么时候从X开车到Y？”

运作原理

对于终端用户

  1. 跑 ./test_custom.sh
  2. 在约4秒内获得结果（并行API调用）
  3. 见两个输出：
    • 彩色ANSI图 （美丽的终端可视化）
    • 简单文本绘图 （Claude Code使用+、o、*字符的纯文本）

克劳德/克劳德代码

当你问“我什么时候从X开车到Y？”：

  1. 快速响应 （<10秒）：

    [Show simple text plot]
🟢 BEST: 5-7 AM (35 min)
🔴 WORST: 2-4 PM (60 min)
💡 Recommendation: Leave before 7 AM

Want more details?

  2. 详细回复 （如果你说是）：

    • 逐小时细分
    • 具体场景
    • 多项选择

关键AI行为

人类现实建议：

  • ✅ “早上5点到7点离开”（合理）
  • ❌ “凌晨2点离开”（对大多数人来说不切实际——人类需要睡眠！）

适应特殊性：

  • 含糊的问题→ 快速回答+询问更多
  • 特定约束→ 计算并提供选项
  • 飞行时间→ 使用缓冲区反向工作

建筑

文件结构

mcp-hackathon/
├── .env                       # API key (gitignored, copy from .env.example)
├── .env.example               # Template for API key
├── requirements.txt           # Python dependencies
├── setup.py                   # Package setup (enables `pip install -e .`)
├── test.sh                    # Quick smoke test (~2 sec)
├── test_custom.sh             # Main usage script (customizable route)
├── outputs/                   # Generated maps and plots (gitignored)
├── cli/
│   └── driveplot_fast.py      # Fast CLI with parallel requests
└── mcp_server/
    ├── __init__.py            # Makes mcp_server a Python package
    ├── server.py              # MCP server (exposes tools to Claude)
    ├── google_maps.py         # Google Maps API integration
    └── utils.py               # Helper functions (LatLng, minute_grid, etc.)

为什么是这些文件？

核心文件：

  • cli/driveplot_fast.py -独立终端工具（无需MCP）
  • mcp_server/server.py -用于Claude集成的MCP服务器
  • mcp_server/google_maps.py -API调用（由CLI和MCP共享）
  • mcp_server/utils.py -共享公用设施
  • mcp_server/__init__.py -Python包所需（启用 from mcp_server import ...)

配置：

  • .env -您的API密钥（从未提交给git）
  • .env.example -新用户模板
  • setup.py -包元数据和依赖关系（需要 pip install -e .)
  • requirements.txt -直接依赖关系列表

测试：

  • test.sh -快速验证（1小时窗口，~2秒）
  • test_custom.sh -实际使用情况（24小时~4秒）

API密钥管理

单一真相来源：

.env file (GOOGLE_MAPS_API_KEY=...)
  ↓
  ├─→ Shell scripts (loaded via `export $(grep -v '^#' .env | xargs)`)
  └─→ Python code (os.getenv("GOOGLE_MAPS_API_KEY"))

仅 mcp_server/google_maps.py 定义：

GOOGLE_KEY = os.getenv("GOOGLE_MAPS_API_KEY", "")

所有其他代码都导入并使用此变量。

演出

  • 并行API调用：最多30个并发请求（第一轮）
  • 使用while循环进行智能重试：仅检索并发性降低的失败请求（10个工作进程）
  • 多轮重试：最多3轮，确保最大成功率
  • 速度：约4秒用于24小时全分析（96个数据点）
  • 120倍加速 vs顺序方法

MCP工具暴露

当作为MCP服务器运行时，Claude可以使用以下工具：

1. geocode(query: str)

  • 将地址转换为坐标
  • 返回带有格式化地址和lat/lng的候选人
  • 示例：“加利福尼亚州伯克利”→ [(37.8715, -122.2730), ...]

2. static_map(origin_lat, origin_lng, dest_lat, dest_lng)

  • 生成谷歌地图静态图像URL
  • 用标记显示路线
  • 返回PNG图像的URL

3. eta_series(...)

  • 获取跨时间范围的流量数据
  • 返回乐观/悲观/平均驾驶时间
  • 参数：
    • origin_lat, origin_lng
    • dest_lat, dest_lng
    • date, start_time, end_time
    • interval_minutes
    • include_plot （可选，适用于Claude聊天中的matplotlib PNG）

使用的谷歌地图API

  • 地理编码API：地址→ 坐标
  • API指南：交通感知路线持续时间
  • 静态映射API：路线可视化

交通模型：

  • optimistic -最佳情况（交通量小）
  • pessimistic -最坏情况（交通繁忙）
  • 平均值-根据两者计算（实际预期）

输出格式

简单文本图（适用于Claude代码）

 66 min |                                  o
 64 min |                                 o ooo
 62 min |                               oo
 ...
 32 min |        **********************
 30 min | +++++++++++++++++++++++++++++++
        +------------------------------------------------------------
          0   1   2   3   4   5   6   7   8   9   10  11  12  ...
          Hour of Day

LEGEND:
  + = Optimistic  |  o = Pessimistic  |  * = Average
  B = Best time   |  W = Worst time

特征：

  • 显示全部24小时
  • 三种交通场景
  • 标记最佳/最差时间
  • 人类可读的x轴（单位/两位数小时的适当间距）
  • 无ANSI代码（以克劳德代码响应呈现）

彩色ANSI图（用于终端）

使用plotext库，布局相同，但颜色美观。

故障排除

API错误

“缺少GOOGLE_MAPS_API_KEY” → Check .env 文件存在并且有您的密钥 → 确保您从以下位置复制 .env.example: cp .env.example .env

“请求已删除” → 在谷歌云控制台中启用API（地理编码、方向、静态地图） → 验证账单是否有效（您每月可获得200美元的免费信用额度）

性能问题

多次重试失败的查询 → 由于速率限制，某些API请求失败 → 脚本自动重试，并发性降低 → 等待完成-大多数查询最终都会成功

慢速（>10秒） → 网络问题 → 稍后再试 → 默认值：30名工人→ 10 重试工人（可在代码中调整）

安装问题

运行MCP服务器时“找不到模块” → Run pip install -e . 以可编辑模式安装软件包

.sh文件上的“权限被拒绝” → Run chmod +x test.sh test_custom.sh

输出文件未保存 → Check outputs/ 文件夹已存在（自动创建） → 验证路径 --save-map 旗帜

成本

非常便宜！

  • 完整的24小时查询（96分）：~0.001美元
  • 200美元/月免费信用=约200000次查询
  • 在开发或正常使用过程中不会达到极限

黑客马拉松评委

我们建造了什么

用于流量分析的生产就绪MCP服务器，具有：

  • ✅ 120倍加速 （10分钟→ 4 秒通过并行处理）
  • ✅ 美丽的终端可视化 （双输出：ANSI+纯文本）
  • ✅ 人性化的人工智能行为 （考虑睡眠/工作时间表）
  • ✅ 智能重试逻辑 （当循环多轮时，只重试失败）
  • ✅ 干净、可发布的代码 （最少的必要文件，全面的文档）

关键创新

  1. 双层响应系统

    • 先快速回答（<10秒）
    • 根据请求进行详细分析
    • 防止缓慢、压倒性的反应

  2. 人类现实约束

    • 不建议凌晨2点出发
    • 考虑工作时间、睡眠需求
    • 实际时间窗口

  3. 双输出格式

    • 终端用户彩色ANSI
    • Claude Code响应的简单文本（+，o，*）
    • 解决ANSI渲染限制

  4. API处理稳健

    • 使用ThreadPoolExecutor的并行请求
    • While循环重试（不仅仅是2次）
    • 智能并发减少（30→10个工人）
    • 失败后的优雅降级

轨道

轨道1：构建MCP

这是一个完整的、可用于生产的MCP服务器，它：

  • 展示有用的工具（地理编码、eta_series、static_map）
  • 解决实际问题（通勤计划、会议日程安排）
  • 适用于Claude Desktop和Claude Code
  • 拥有出色的文档
  • 已准备好发布和使用

高级用法

自定义时间范围

python cli/driveplot_fast.py \
  --origin "Your Home" \
  --destination "Your Work" \
  --date 2025-11-20 \
  --start 06:00 --end 10:00 \  # Morning only
  --interval 30 \               # Every 30 min
  --ascii --yes

不同的间隔

  • 15分钟：详细分析（96个数据点，约4秒）
  • 30分钟：平衡（48分，约2秒）
  • 60分钟：快速概述（24分，约1秒）

将地图保存到输出/

python cli/driveplot_fast.py \
  --origin "Berkeley, CA" \
  --destination "San Francisco, CA" \
  --date 2025-11-20 \
  --ascii --save-map outputs/my_route.png --yes

安全

✅ API密钥受保护：

  • 存储在 .env （忽略）
  • 从未致力于版本控制
  • 单一事实来源
  • 易于旋转
  • 提供模板(.env.example)

✅ 没有硬编码的秘密 代码库中的任何位置

✅ 最佳实践：

  • 通过python dotenv实现环境变量
  • 代码和配置的明确分离
  • 综合.gitignore

未来改进

扩展思路：

  • 添加Apple Maps支持（已为此构建）
  • 历史数据跟踪（比较随时间变化的交通模式）
  • 日历集成（自动建议出发时间）
  • 多路线比较（A与B）
  • 带Gradio的Web UI（用于Track 2提交）

许可证

MIT许可证 -自由使用！

这是MCP服务器的标准许可证。请随意：

  • 用于商业项目
  • 修改和重新分发
  • 整合到闭源软件中

鸣谢

为 拥抱脸MCP黑客马拉松（轨道1）

使用的技术：

  • FastMCP -MCP服务器框架
  • 谷歌地图平台API -地理编码、方向、静态地图
  • 犁 -终端绘图
  • 富有的 -漂亮的终端输出
  • 线程池执行器 -并行API请求

问题？

对于问题或疑问：

  1. 检查上面的故障排除部分
  2. 验证您的 .env 文件设置正确
  3. 跑 ./test.sh 验证安装
  4. 检查云控制台中是否启用了Google Maps API

相关 MCP