JinDaGe - mcp-travel-assistant MCP Details

article

README

🚀 🌟 MCP旅行 concierge 服务器

终极人工智能旅行规划助手 - 一个全面的MCP（模型上下文协议）服务器，它将谷歌旅行服务的精华与Amadeus专业系统相结合。

🚀 快速开始

本旅行 concierge 服务器将两个强大的旅行平台整合为一个全面的解决方案：

🌐 谷歌旅行服务（通过 SerpAPI） - 面向消费者的航班、酒店和活动搜索
🏢 Amadeus全球分销系统 - 专业的旅行行业库存和定价

MCP人工智能旅行助手 - 观看视频

</a>

让您兼得二者之长：既有面向消费者的便捷性，又有专业的深度！

✨ 主要特性

✈️ 双航班搜索

谷歌航班：面向消费者的定价、热门航线、价格洞察
Amadeus GDS：专业的航空公司库存、详细的票价等级、实时可用性

🏨 全面的酒店搜索

谷歌酒店：度假租赁、精品酒店、消费者评价
Amadeus酒店：专业价格、实时可用性、商务旅行优化

🎭 完整的活动与体验发现

谷歌活动：当地节日、音乐会、文化活动
Amadeus活动：专业旅游、精选体验、经过验证的运营商

🌍 附加服务

地理编码与距离计算：精确的位置服务
天气智能：实时天气状况和预报
货币兑换：实时汇率
财务跟踪：旅行行业股票监测

📦 安装指南

1. 克隆并安装依赖项

# 克隆仓库
git clone https://github.com/your-username/mcp_travelassistant.git
cd mcp_travelassistant

# 安装依赖项
pip install -r requirements.txt

2. 设置环境变量

在项目根目录下创建一个 .env 文件，并填入您的 API 密钥：

# 复制示例环境文件
cp env.example .env

编辑 .env 文件，填入您的实际 API 密钥：

# 必需的 API 密钥
SERPAPI_KEY=your_serpapi_key_here
AMADEUS_API_KEY=your_amadeus_api_key_here
AMADEUS_API_SECRET=your_amadeus_api_secret_here
EXCHANGE_RATE_API_KEY=your_exchange_rate_api_key_here

API 密钥获取途径：

SERPAPI_KEY：从 SerpAPI 获取
AMADEUS_API_KEY 和 AMADEUS_API_SECRET：从 Amadeus for Developers 获取
EXCHANGE_RATE_API_KEY：从 ExchangeRate-API 获取

3. 运行服务器

python travel_server.py

🔧 MCP 配置

针对 Claude Desktop

将以下配置添加到您的 Claude Desktop 配置文件中（通常位于 ~/.cursor/mcp.json 或 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "travel-concierge": {
      "command": "python",
      "args": ["combined_travel_server.py"],
      "cwd": "/path/to/your/mcp_travelassistant",
      "env": {
        "SERPAPI_KEY": "your_serpapi_key_here",
        "AMADEUS_API_KEY": "your_amadeus_api_key_here", 
        "AMADEUS_API_SECRET": "your_amadeus_api_secret_here",
        "EXCHANGE_RATE_API_KEY": "your_exchange_rate_api_key_here"
      }
    }
  }
}

针对 UV 包管理器

如果您使用的是 UV，可以使用以下配置：

{
  "mcpServers": {
    "travel-concierge": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/your/mcp_travelassistant/",
        "run", "python", "combined_travel_server.py"
      ],
      "env": {
        "SERPAPI_KEY": "your_serpapi_key_here",
        "AMADEUS_API_KEY": "your_amadeus_api_key_here",
        "AMADEUS_API_SECRET": "your_amadeus_api_secret_here", 
        "EXCHANGE_RATE_API_KEY": "your_exchange_rate_api_key_here"
      }
    }
  }
}

针对 HTTP 模式

如果您更喜欢以 HTTP 模式运行服务器：

{
  "mcpServers": {
    "travel-concierge": {
      "command": "npx",
      "args": [
        "@modelcontextprotocol/client-http",
        "http://localhost:8000/"
      ]
    }
  }
}

然后使用以下命令运行服务器：python travel_server.py --transport http --port 8000

📚 详细文档

🎯 可用工具

✈️ 航班搜索工具

| 工具 | 提供商 | 描述 | |------|----------|-------------| | search_flights_serpapi() | 谷歌航班 | 带有价格洞察的面向消费者的航班搜索 | | search_flights_amadeus() | Amadeus GDS | 专业的航空公司库存和票价搜索 |

🏨 酒店搜索工具

| 工具 | 提供商 | 描述 | |------|----------|-------------| | search_hotels_serpapi() | 谷歌酒店 | 带有评价的面向消费者的酒店搜索 | | search_hotels_amadeus_by_city() | Amadeus GDS | 基于城市的专业酒店搜索 | | search_hotels_amadeus_by_geocode() | Amadeus GDS | 基于坐标的专业搜索 | | search_hotel_offers_amadeus() | Amadeus GDS | 实时酒店可用性和定价搜索 |

🎭 活动与体验工具

| 工具 | 提供商 | 描述 | |------|----------|-------------| | search_events_serpapi() | 谷歌活动 | 当地活动和文化体验搜索 | | search_activities_amadeus() | Amadeus GDS | 专业旅游和活动搜索 |

🌍 实用工具

| 工具 | 提供商 | 描述 | |------|----------|-------------| | geocode_location() | Nominatim | 将地址转换为坐标 | | calculate_distance() | Geopy | 计算地点之间的距离 | | get_weather_forecast() | Open-Meteo | 用于旅行规划的天气预报 | | get_current_conditions() | Open-Meteo | 实时天气状况 | | convert_currency() | ExchangeRate-API | 实时货币兑换 | | lookup_stock() | 谷歌财经 | 旅行行业股票跟踪 |

💻 使用示例

综合旅行规划

# 从多个提供商搜索航班
google_flights = search_flights_serpapi(
    departure_id="JFK",
    arrival_id="CDG", 
    outbound_date="2025-06-15",
    return_date="2025-06-22",
    adults=2
)

amadeus_flights = search_flights_amadeus(
    originLocationCode="JFK",
    destinationLocationCode="CDG",
    departureDate="2025-06-15",
    returnDate="2025-06-22",
    adults=2
)

酒店搜索策略

# 首先获取坐标
location = geocode_location("Paris city center")

# 通过谷歌酒店进行面向消费者的搜索
google_hotels = search_hotels_serpapi(
    location="Paris city center",
    check_in_date="2025-06-15", 
    check_out_date="2025-06-22"
)

# 通过 Amadeus 进行专业搜索
amadeus_hotels = search_hotel_offers_amadeus(
    cityCode="PAR",
    checkInDate="2025-06-15",
    checkOutDate="2025-06-22"
)

完整旅行规划

# 1. 获取目的地坐标
coords = geocode_location("Paris, France")

# 2. 查看天气
weather = get_weather_forecast(
    latitude=coords['latitude'],
    longitude=coords['longitude']
)

# 3. 查找活动
events = search_events_serpapi(
    query="concerts museums",
    location="Paris",
    date_filter="week"
)

# 4. 进行货币兑换以进行预算规划
budget_eur = convert_currency(
    from_currency="USD",
    to_currency="EUR", 
    amount=2000
)

🌟 最佳实践

1. 双平台搜索策略

始终在两个平台上搜索航班和酒店，以确保获得最优惠的价格和全面的选择。

2. 先确定位置

先使用 geocode_location() 获取精确坐标，然后使用这些坐标进行基于位置的搜索。

3. 整合天气信息

在确定活动计划之前，使用 get_weather_forecast() 查看天气预报。

4. 货币规划

使用 convert_currency() 进行准确的国际旅行预算规划。

🔄 Docker 支持

构建并运行

# 构建 Docker 镜像
docker build -t travel-concierge .

# 使用环境变量运行
docker run -p 8000:8000 \
  -e SERPAPI_KEY=your_key \
  -e AMADEUS_API_KEY=your_key \
  -e AMADEUS_API_SECRET=your_secret \
  -e EXCHANGE_RATE_API_KEY=your_key \
  travel-concierge

Docker Compose

# 复制环境文件
cp env.example .env

# 编辑 .env 文件，填入您的 API 密钥
# 然后运行：
docker-compose up

🐛 故障排除

常见问题

缺少 API 密钥

Error: SERPAPI_KEY environment variable is required

解决方案：在 .env 文件或环境变量中设置您的 API 密钥。

端口已被占用

Error: Port 8000 is already in use

解决方案：使用 --port 8001 指定不同的端口。

Amadeus 认证错误

Error: Invalid API credentials

解决方案：验证您的 Amadeus API 密钥和密钥是否正确。

健康检查

当以 HTTP 模式运行时，访问 http://localhost:8000/health 以验证服务器是否正常运行。

📈 性能

统一架构：单个服务器减少了开销和复杂性
并发请求：有效处理多个并发请求
速率限制：内置外部 API 调用的速率限制
错误处理：全面的错误处理和恢复机制

🤝 贡献

分叉仓库
创建功能分支 (git checkout -b feature/amazing-feature)
进行更改
如有必要，添加测试
提交更改 (git commit -m 'Add some amazing feature')
推送到分支 (git push origin feature/amazing-feature)
打开拉取请求

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

🙏 致谢

Amadeus for Developers - 专业的旅行行业数据
SerpAPI - 谷歌服务集成
Open-Meteo - 天气数据服务
ExchangeRate-API - 货币兑换服务
Nominatim/OpenStreetMap - 地理编码服务

🆘 支持

如需支持，请：

查看上述文档
查看示例环境文件
打开一个包含详细问题信息的问题单

旅途愉快！ ✈️🏨🎭🌍