Travel Planner MCP

旅行计划MCP服务器

模型上下文协议（MCP）服务器，使用谷歌地图API和OpenWeatherMap提供智能旅行路线规划功能。此服务器接受目的地列表，并为每个目的地计划具有真实驾驶方向、距离、填充时间估计和季节性天气信息的优化路线。

特性

• 谷歌地图集成：使用Google Maps Directions API准确估计路线和时间
• 季节性天气报告：使用OpenWeatherMap提供每个目的地的当前天气和季节趋势
• 带填充的时间估计：为休息站、交通和延误提供20%的行程时间填充
• 路线优化：使用实际行驶距离规划通过多个目的地的高效路线
• 逐段导航：包括旅程每一段的关键导航步骤
• 多种优化策略：在最短距离或字母顺序之间进行选择
• 灵活的起点：可选择指定旅程的起点
• 完整行程生成：创建包含旅行日期、探险日和天气预报的每日日程表
• 综合录井：所有MCP请求、API调用以及用于调试和监控的响应的详细日志

安装

先决条件

• 达到1.22或更高
• MCP兼容客户端（如Claude Desktop、Cline）
• 启用了方向API和距离矩阵API的谷歌地图API键
• OpenWeatherMap API密钥（提供免费层）

谷歌地图API设置

1. 首选 谷歌云控制台
2. 创建新项目或选择现有项目
3. 启用以下API：

- API指南 - 距离矩阵API

1. 创建API密钥：

- 导航到“API和服务”>“凭据” - 单击“创建凭据”>“API密钥” - （推荐）仅将密钥限制为方向和距离矩阵API

1. 将API键设置为环境变量：

   export GOOGLE_MAPS_API_KEY="your_api_key_here"

OpenWeatherMap API设置

1. 首选 OpenWeatherMap
2. 注册一个免费帐户
3. 导航到API密钥部分
4. 复制您的API密钥（免费层包括每天1000个呼叫）
5. 将API键设置为环境变量：

   export OPENWEATHER_API_KEY="your_openweather_api_key_here"

从源代码构建

# Clone the repository
git clone https://github.com/rmcconnachie/travel-planner-mcp.git
cd travel-planner-mcp

# Download dependencies
go mod download

# Build the server
go build -o travel-planner-mcp

配置

克劳德桌面版

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

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "travel-planner": {
      "command": "/absolute/path/to/travel-planner-mcp",
      "env": {
        "GOOGLE_MAPS_API_KEY": "your_google_maps_api_key_here",
        "OPENWEATHER_API_KEY": "your_openweather_api_key_here"
      }
    }
  }
}

其他MCP客户端

配置stdio传输以运行 travel-planner-mcp 两者均可执行 GOOGLE_MAPS_API_KEY 和 OPENWEATHER_API_KEY 环境变量设置。

用法

服务器提供了一个工具： plan_route

参数

• 目的地 （必填）：以逗号分隔的目的地城市列表

- 例子： "Paris, London, Berlin, Rome" - 可以是谷歌地图识别的任何位置

• start_location （可选）：旅程的起点

- 如果未指定，则默认为列表中的第一个目标 - 例子： "London"

• 优化 （可选）：路线优化策略

- "shortest" （默认）：使用谷歌地图实际行驶距离优化最小总距离 - "alphabetical"：按字母顺序订购目的地

• 开始日期 （可选）：生成完整行程的行程开始日期

- 格式： "YYYY-MM-DD" （例如。， "2025-01-15") - 提供后，生成包含日期的每日日程表 - 例子： "2025-06-01"

• 天_目的地 （可选）：每个目的地的探索天数

- 违约： 2 - 适用于路线中的每个目的地 - 不包括旅行天数（旅行天数会自动添加） - 例子： 3 在每个城市进行为期3天的探索

例子

基本路线规划

Plan a route through Paris, London, Berlin, and Rome

服务器将返回一份详细的行程，其中包含：

• 总距离（公里）
• 预计旅行时间
• 行程时间有20%的填充（用于休息站、交通等）
• 循序渐进的路线段，包括：

- 个人距离 - 预计时间 - 延迟时间 - 季节性天气信息（温度、条件、降水等） - 逐向导航关键步骤

• 最终目的地排序列表

起始位置

Plan a route starting from London through Paris, Berlin, and Rome

按字母顺序排列

Plan a route through Tokyo, Sydney, New York, and Paris using alphabetical optimization

完整行程

Plan a trip starting on January 15, 2025 visiting Paris, Rome, and Barcelona with 2 days at each destination

行程功能创建了一个逐日日程表，显示：

• 包含路线详细信息、距离和持续时间的旅行天数
• 每个目的地的探索日
• 每个地点的天气信息
• 从开始到结束日期的完整行程时间表
• 总行程时间

样本输出

# Travel Route Plan

**Total Distance:** 1453.20 km
**Estimated Travel Time:** 14h 32m
**With 20% Padding:** 17h 26m (includes rest stops, traffic, etc.)

## Itinerary

1. **London** → **Paris**
   - Distance: 456.30 km
   - Estimated Time: 4h 52m
   - With Padding: 5h 50m
   - Mode: driving
   - Seasonal Weather:
     • Month: January
     • Avg Temp: 7.2°C (45.0°F)
     • Conditions: Cloudy
     • Light rain expected
     • Humidity: 81%
     • Precipitation: 51.2 mm
     • Wind Speed: 19.3 km/h
   - Key Steps:
     • Head east on A1
     • Take the Channel Tunnel
     • Continue on A16 toward Paris

...

行程输出示例（带日期）

## Full Itinerary

**Trip Duration:** January 15, 2025 to January 20, 2025 (6 days)

### Day 1 - Wednesday, January 15, 2025
**Travel Day:** Paris → Rome

- Distance: 1420.52 km
- Estimated Duration: 13h 15m
- Travel from Paris to Rome

**Weather in Paris:**
- 7.2°C (45.0°F), Cloudy
- Light rain expected

### Day 2 - Thursday, January 16, 2025
**Exploring:** Rome

- Full day exploring Rome - Visit local attractions, museums, and restaurants

**Weather in Rome:**
- 12.8°C (55.0°F), Partly Cloudy

### Day 3 - Friday, January 17, 2025
**Exploring:** Rome

- Full day exploring Rome - Visit local attractions, museums, and restaurants

### Day 4 - Saturday, January 18, 2025
**Travel Day:** Rome → Barcelona

- Distance: 1360.80 km
- Estimated Duration: 12h 48m
- Travel from Rome to Barcelona

### Day 5 - Sunday, January 19, 2025
**Exploring:** Barcelona

- Full day exploring Barcelona - Visit local attractions, museums, and restaurants

**Weather in Barcelona:**
- 10.5°C (50.9°F), Sunny

### Day 6 - Monday, January 20, 2025
**Exploring:** Barcelona

- Full day exploring Barcelona - Visit local attractions, museums, and restaurants

运作原理

该服务器集成了多个API，以提供全面的旅行计划：

1. 目的地输入：接受谷歌地图识别的任何位置（城市、地址、地标）
2. 路线优化：使用Google Maps Distance Matrix API查找目的地之间的最短路线
3. 详细说明：从Google Maps directions API检索转弯方向
4. 天气数据：从OpenWeatherMap获取每个目的地的季节性天气趋势
5. 时间计算：根据当前道路状况提供真实世界的旅行时间估计
6. 填充：将所有时间估计值增加20%，以考虑休息站、交通延误和意外事件
7. 行程生成：提供日期后，创建包含旅行和探索天数的完整日程表

建筑

travel-planner-mcp/
├── main.go              # MCP server entry point and tool handlers
├── planner/
│   └── planner.go       # Route planning, Google Maps & OpenWeatherMap integration
├── go.mod               # Go module definition
└── README.md            # This file

关键组件

• MCP协议处理程序：实现MCP通信的stdio传输
• 谷歌地图集成：调用方向API和距离矩阵API以获取实际路由数据
• OpenWeatherMap集成：获取目的地的当前天气和季节趋势
• 航路优化器：使用实际行驶距离的贪婪最近邻算法
• 时间估计：使用可配置的填充百分比计算行程时间
• 天气分析：提供季节性天气模式，以帮助计划最佳旅行时间

发展

运行测试

go test ./...

配电楼

# Build for current platform
go build -o travel-planner-mcp

# Cross-compile for other platforms
GOOS=linux GOARCH=amd64 go build -o travel-planner-mcp-linux
GOOS=windows GOARCH=amd64 go build -o travel-planner-mcp.exe
GOOS=darwin GOARCH=arm64 go build -o travel-planner-mcp-macos-arm64

调整填充百分比

要修改时间填充，请编辑 paddingPercentage 变量in planner/planner.go:

paddingPercentage := 0.20 // 20% padding for rest stops, traffic, etc.

日志记录

服务器为stderr提供全面的日志记录，用于监控和调试：

日志类别

• 初创公司：服务器初始化、API密钥验证、工具注册
• MCP请求：带有完整参数详细信息的传入工具调用
• API调用：谷歌地图和OpenWeatherMap API请求和响应
• 路线规划：距离计算、优化进度
• MCP响应：响应生成和定时信息

查看日志

克劳德桌面版：日志会写入stderr，可以在以下位置查看：

• macOS: ~/Library/Logs/Claude/mcp*.log
• 视窗: %APPDATA%\Claude\logs\mcp*.log

终端：直接运行时，终端中会出现日志：

./travel-planner-mcp 2> server.log  # Redirect logs to file

日志输出示例

2026/01/30 10:15:23.456789 main.go:18: === Travel Planner MCP Server Starting ===
2026/01/30 10:15:23.456890 main.go:23: Google Maps API key configured
2026/01/30 10:15:23.456901 main.go:29: OpenWeatherMap API key configured
2026/01/30 10:15:23.456912 main.go:36: MCP Server initialized: Travel Planner v1.0.0
2026/01/30 10:15:23.456923 main.go:51: Registered tool: plan_route
2026/01/30 10:15:23.456934 main.go:52: === Server ready, listening on stdio ===
2026/01/30 10:16:45.123456 main.go:60: === MCP Tool Request Received ===
2026/01/30 10:16:45.123467 main.go:61: Tool: plan_route
2026/01/30 10:16:45.123478 main.go:65: Arguments:
{
  "destinations": "Paris, London, Berlin",
  "optimization": "shortest"
}
2026/01/30 10:16:45.234567 planner.go:410: Getting directions: Paris → London
2026/01/30 10:16:45.789012 planner.go:450: Distance: 456.30 km, Duration: 4h52m
2026/01/30 10:16:45.890123 planner.go:555: Fetching weather for: London
2026/01/30 10:16:46.012345 planner.go:623: Weather: 7.2°C, Cloudy
2026/01/30 10:16:47.456789 main.go:143: === MCP Tool Response Ready (took 2.333333s) ===

许可证

MIT许可证

贡献

欢迎投稿！请随时提交问题或拉取请求。

技术细节

谷歌地图API集成

服务器使用两个谷歌地图API：

1. API指南：检索详细的路线信息，包括：

- 建议路线规划指示 - 每条腿的距离和持续时间 - 导航步骤

1. 距离矩阵API：在路线优化期间用于：

- 计算多个目的地之间的距离 - 查找最近的下一个目的地 - 优化整体路线

时间填充

服务器为所有时间估计添加了一个可配置的填充百分比（默认值：20%）。这说明了：

• 休息站和用餐休息时间
• 交通延误
• 意外的迂回
• 加油停止
• 过境点（国际航线）

路线优化

“最短”优化使用贪婪的最近邻方法：

1. 从指定的起始位置（或第一个目的地）开始
2. 查询Google Maps Distance Matrix API以获取到所有未访问目的地的距离
3. 选择最近的目的地
4. 重复此操作，直到访问完所有目的地

这提供了使用真实驾驶距离的最佳路线的良好近似值。

故障排除

API关键问题

谷歌地图API： 如果您看到“GOOGLE_MAPS_API_KEY未设置”错误：

1. 验证是否设置了环境变量： echo $GOOGLE_MAPS_API_KEY
2. 请确保API密钥有效并且已启用所需的API
3. 检查密钥是否没有阻止访问的使用限制
4. 在Claude Desktop配置中，确保 env 部分配置正确

OpenWeatherMap API： 如果没有出现天气信息：

1. 验证是否设置了环境变量： echo $OPENWEATHER_API_KEY
2. 在检查您的API密钥是否处于活动状态https://home.openweathermap.org/api_keys
3. 注意：新的API密钥可能需要几个小时才能激活
4. 如果没有设置API键，服务器将在没有天气数据的情况下工作（天气部分将被省略）

服务器未出现在Claude Desktop中

1. 验证中的路径 claude_desktop_config.json 是绝对的
2. 确保二进制文件具有执行权限： chmod +x travel-planner-mcp
3. 验证API密钥是否设置在 env 部分
4. 检查Claude Desktop日志中的错误消息
5. 配置更改后重新启动Claude Desktop

路线规划失败

如果无法计算路线：

1. 验证目的地是否被谷歌地图识别（尝试在Maps.Google.com上搜索）
2. 检查方向API和距离矩阵API是否在谷歌云控制台中启用
3. 确保您没有超过API配额限制
4. 先尝试知名城市来测试设置

构建错误

# Clear module cache and rebuild
go clean -modcache
go mod download
go build

API成本

谷歌地图API 采用基于使用量的定价：

• API指南：每项请求约0.005美元
• 距离矩阵API：每个要素约0.005美元

谷歌每月提供200美元的免费使用费，大致包括：

• 20000个方向API请求
• 20000距离矩阵API元素

OpenWeatherMap 定价：

• 免费层：每天1000个API调用（对于大多数用例来说足够）
• 包括当前天气数据和地理编码
• 如果需要，升级到付费计划以拨打更多电话

对于典型的使用（规划3-5条目的地路线），您可以在两个免费等级中每月规划数百条路线。

监控您的使用情况：

• 谷歌地图：https://console.cloud.google.com/apis/dashboard
• OpenWeatherMap：https://home.openweathermap.org/statistics