Flight Ticket MCP Server

一个基于模型上下文协议(MCP)的航空机票查询服务器。该服务器为AI助手提供标准化的航班实时动态查询功能接口。

概述

Flight Ticket MCP Server 实现了供航空机票相关查询操作的工具和资源。它作为AI助手与航空服务系统之间的桥梁，专注于航班实时动态查询功能。

该服务器采用模块化架构，将核心功能、工具和实用程序分离，使其具有高度的可维护性和可扩展性。

功能特性

航班路线查询

• 根据出发地、目的地和出发日期查询可用航班
• 支持282个国内城市和机场代码
• 智能城市名称解析（支持城市名、机场代码、完整格式）
• 实时航班价格和航班时刻信息
• 航空公司和机型信息
• 航站楼和登机口信息
• 价格统计和航空公司分布
• 格式化输出结果

航班中转路线查询

• 根据出发地、中转地、目的地查询联程航班
• 支持自定义最小和最大中转时间（默认2-5小时）
• 智能筛选符合中转时间要求的航班组合
• 提供完整的两段航程信息
• 支持国内外航线中转查询
• 详细的中转时间计算和验证

天气信息查询

• 按经纬度查询：精确地理位置天气查询
• 按城市名查询：支持主要城市直接查询
• 支持历史、当前和未来天气数据
• 提供温度、湿度、风速、天气状况等详细信息
• 自动处理时区和日期范围
• 支持武汉、北京、上海等主要城市预设

航班信息查询

• 根据航班号查询详细的航班信息
• 包含航班状态、座位配置、价格信息
• 提供天气信息（出发地和目的地）
• 显示航班基本信息（航空公司、机型、航线类型）
• 详细的航站楼、登机口信息
• 实时动态状态（准时、延误、登机、飞行中等）
• 座位价格和可用性信息
• 附加服务信息（餐食、WiFi、娱乐系统等）

实时航班跟踪

• 航班实时状态查询：查询航班实时位置和状态
• 机场周边航班查询：查询指定机场周边30公里范围内的所有航班
• 区域航班查询：查询指定地理区域内的所有实时航班
• 批量航班跟踪：同时跟踪多个航班的实时状态
• 支持中国主要机场代码（PEK、PVG、CAN等70+机场）
• 提供详细的航班位置、速度、高度、状态信息
• 无需认证的公开API，实时更新航班数据

日期时间工具

• 获取当前系统日期（YYYY-MM-DD格式）
• 获取当前系统日期时间（YYYY-MM-DD HH:mm:ss格式）
• 为其他功能提供标准化的日期时间支持
• 自动处理时区和格式转换

数据处理与智能化

• 智能城市解析：支持多种城市输入格式（城市名、机场代码、完整格式）
• 参数验证：全面的输入参数验证和错误处理
• 结果格式化：统一的JSON格式输出，便于AI助手解析
• 错误恢复：完善的异常处理和降级机制
• 日志记录：详细的操作日志和调试信息

技术架构

核心模块 (Core)

• 航班数据模型和结构定义
• 机场、航空公司、航班、价格等数据模型
• 航班中转和座位配置数据结构

工具模块 (Tools)

• 航班搜索工具 (flight_search_tools.py) - 航班路线查询功能
• 航班中转工具 (flight_transfer_tools.py) - 多段航程和中转查询
• 航班信息工具 (flight_info_tools.py) - 根据航班号查询详细信息
• 实时航班跟踪工具 (simple_opensky_tools.py) - 基于OpenSky Network的实时航班跟踪
• 天气查询工具 (weather_tools.py) - 基于经纬度和城市的天气查询
• 日期时间工具 (date_tools.py) - 日期时间获取和处理

实用工具 (Utils)

• 城市字典 (cities_dict.py) - 282个城市和机场代码映射
• 数据验证器 (validators.py) - 输入参数验证和格式检查
• 日期工具 (date_utils.py) - 日期格式化和时区处理
• API客户端 (api_client.py) - HTTP请求封装和错误处理

MCP集成层

• FastMCP服务器 - 基于FastMCP框架的MCP协议实现
• 多传输协议支持 - stdio、SSE、HTTP传输协议
• 工具注册管理 - 统一的工具注册和调用机制
• 环境配置管理 - 灵活的配置和环境变量支持

支持的传输协议

本服务器支持三种传输协议：

1. sse - Server-Sent Events（默认，适用于Web应用）
2. stdio - 标准输入输出（适用于Claude Desktop）
3. streamable-http - 可流式HTTP（适用于HTTP客户端）

安装

前置要求

• Python 3.11 或更高版本
• pip 包管理器（或 uvx 工具）

方式一：从PyPI安装（推荐）

# 使用pip安装
pip install flight-ticket-mcp-server

# 或使用uvx直接运行（无需安装）
uvx flight-ticket-mcp-server

# 或使用uvx安装后运行
uvx --install flight-ticket-mcp-server

方式二：本地开发安装

# 克隆或下载项目
cd FlightTicketMCP

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

# 或从本地源码安装
pip install -e .

uvx 使用说明

uvx 是一个现代的Python包运行工具，可以直接运行PyPI包而无需先安装到系统环境：

# 安装uv（包含uvx工具）
pip install uv

# 直接运行MCP服务器（无需安装）
uvx flight-ticket-mcp-server

# 使用最新版本（推荐）
uvx flight-ticket-mcp-server@latest

# 带参数运行
uvx flight-ticket-mcp-server --help

# 指定版本运行
uvx flight-ticket-mcp-server==1.0.1

# 强制重新安装最新版本
uvx flight-ticket-mcp-server@latest --help

uvx 的优势：

• 🚀 无需污染全局Python环境
• 📦 自动管理虚拟环境
• 🔄 支持直接运行最新版本
• 🛡️ 隔离依赖，避免冲突

启动方式

1. 直接启动（默认SSE模式）

# 使用主启动文件（默认启动SSE模式，监听127.0.0.1:8000）
python flight_ticket_server.py

# 或者直接运行main.py
python main.py

2. 调试模式启动

# 启用调试模式，会输出详细日志
set MCP_DEBUG=true
python flight_ticket_server.py

# Linux/macOS
export MCP_DEBUG=true
python flight_ticket_server.py

3. 不同传输协议启动

SSE模式（默认）

# 直接启动，使用默认SSE配置（127.0.0.1:8000）
python flight_ticket_server.py

stdio模式

# Windows
set MCP_TRANSPORT=stdio
python flight_ticket_server.py

# Linux/macOS
export MCP_TRANSPORT=stdio
python flight_ticket_server.py

HTTP模式

# Windows
set MCP_TRANSPORT=streamable-http
set MCP_HOST=127.0.0.1
set MCP_PORT=8000
python flight_ticket_server.py

# Linux/macOS
export MCP_TRANSPORT=streamable-http
export MCP_HOST=127.0.0.1
export MCP_PORT=8000
python flight_ticket_server.py

4. 环境变量配置

使用 .env 文件（推荐）

项目提供了 .env.example 文件作为配置模板：

1. 复制配置模板：

   # 复制配置模板
   cp .env.example .env
   

2. 编辑配置文件：

... View full README on GitHub