Aviationstack Mcp

Aviationstack MCP 服务

本项目是一个 MCP（Model Context Protocol）服务，提供一组用于与 AviationStack API 交互的工具。它公开了用于获取实时和未来航班数据、飞机与机型详情以及核心参考数据（机场、航空公司、航线、税费）的端点，使你可以轻松地将航空数据集成到应用中。

你还可以在以下知名的 MCP 服务仓库中找到 Aviationstack MCP 服务，方便获取：

• modelcontextprotocol/servers
• punkpeye/awesome-mcp-servers
• glama
• smithery
• mcpservers.org

演示

https://github.com/user-attachments/assets/9325fcce-8ecc-4b01-8923-4ccb2f6968f4

功能

• 按航班号查询单个航班
• 获取特定航空公司的航班
• 按日期获取历史航班
• 检索机场的到达和出发时刻表
• 获取未来航班时刻表（从明天起至约 12 个月后）
• 获取随机机型
• 获取随机飞机的详细信息
• 获取随机国家的详细信息
• 获取随机城市的详细信息
• 列出机场、航空公司、航线和税费

所有端点均以 MCP 工具的形式实现，可在兼容 MCP 的环境中直接使用。

每个工具都返回相同的 JSON 信封结构。成功时：{"ok": true, "count": N, "data": [...]}，list_* 工具还会额外返回 pagination 块，无匹配结果时返回 message。失败时：{"ok": false, "context": "...", "error": "..."}。任何 limit 每次调用最多限制为 100 条记录。

前置条件

• Aviationstack API Key（你可以从 Aviationstack 获取免费的 API Key）
• Python 3.13 或更高版本
• 已安装 uv 包管理器

可用工具

工具	描述	参数
get_flight_status(flight_iata: str, flight_date: str = "")	根据 IATA 航班号查询单个航班，可查询今天或指定日期的航班。	- flight_iata：航班 IATA 编号（例如 "AA100"） - flight_date：可选日期，格式为 YYYY-MM-DD
flights_with_airline(airline_name: str, number_of_flights: int, flight_status: str = "")	获取指定航空公司的实时航班。	- airline_name：航空公司名称（例如 "Delta Air Lines"） - number_of_flights：返回的航班数量 - flight_status：可选的状态筛选：scheduled、active、landed、cancelled、incident、diverted
historical_flights_by_date(flight_date: str, number_of_flights: int, airline_iata: str = "", dep_iata: str = "", arr_iata: str = "")	获取某一天的历史航班（Basic 套餐及以上）。	- flight_date：日期，格式为 YYYY-MM-DD - number_of_flights：返回的航班数量 - airline_iata：可选的航空公司 IATA 筛选条件 - dep_iata：可选的出发机场 IATA 筛选条件 - arr_iata：可选的到达机场 IATA 筛选条件
flight_arrival_departure_schedule(airport_iata_code: str, schedule_type: str, airline_name: str, number_of_flights: int)	获取指定机场和航空公司今天的到达或出发航班信息板。仅限当天。	- airport_iata_code：机场的 IATA 代码（例如 "JFK"） - schedule_type："arrival" 或 "departure" - airline_name：航空公司名称 - number_of_flights：返回的航班数量
future_flights_arrival_departure_schedule(airport_iata_code: str, schedule_type: str, airline_iata: str, date: str, number_of_flights: int)	获取指定机场、航空公司和未来日期的计划航班。涵盖明天至约 12 个月后，包括未来 7 天。	- airport_iata_code：机场的 IATA 代码 - schedule_type："arrival" 或 "departure" - airline_iata：航空公司的 IATA 代码（例如 "DL" 代表 Delta） - date：日期，格式为 YYYY-MM-DD，从明天起至约 12 个月后 - number_of_flights：返回的航班数量
random_aircraft_type(number_of_aircraft: int)	从数据集中的随机偏移位置获取机型。	- number_of_aircraft：返回的机型数量
random_airplanes_detailed_info(number_of_airplanes: int)	从数据集中的随机偏移位置获取飞机的详细信息。	- number_of_airplanes：返回的飞机数量
random_countries_detailed_info(number_of_countries: int)	从数据集中的随机偏移位置获取国家/地区的详细信息。	- number_of_countries：返回的国家/地区数量
random_cities_detailed_info(number_of_cities: int)	从数据集中的随机偏移位置获取城市的详细信息。	- number_of_cities：返回的城市数量
list_airports(limit: int = 10, offset: int = 0, search: str = "")	列出机场。	- limit：返回的结果数量 - offset：分页偏移量 - search：可选的搜索查询
list_airlines(limit: int = 10, offset: int = 0, search: str = "")	列出航空公司。	- limit：返回的结果数量 - offset：分页偏移量 - search：可选的搜索查询
list_routes(limit: int = 10, offset: int = 0, airline_iata: str = "", dep_iata: str = "", arr_iata: str = "")	列出航线。	- limit：返回的结果数量 - offset：分页偏移量 - airline_iata：可选的航空公司 IATA 筛选条件 - dep_iata：可选的出发机场 IATA 筛选条件 - arr_iata：可选的到达机场 IATA 筛选条件
list_taxes(limit: int = 10, offset: int = 0, search: str = "")	列出航空税费。	- limit：返回的结果数量 - offset：分页偏移量 - search：可选的搜索查询

提示词

该服务提供可复用的提示词，引导模型使用正确的工具。

提示词	参数	用途
plan_flight_status_lookup	flight_iata、flight_date	查询某个特定航班，并解释其代码共享航班。
plan_airline_flight_lookup	airline_name、number_of_flights	查询某家航空公司的实时航班。
plan_future_schedule_lookup	airport_iata_code、date、schedule_type	查询未来的机场时刻表。
plan_reference_data_lookup	data_type、search	浏览机场、航空公司、航线或税费参考数据。

资源

资源	URI	内容
server_metadata	aviationstack://meta/server	API 基础 URL 以及可接受的 API key 变量。
aviationstack_endpoints	aviationstack://meta/endpoints	各工具所调用的 Aviationstack 端点。
tool_input_examples	aviationstack://examples/tool-input/{tool_name}	给定工具的示例请求负载。

开发

• 主服务逻辑位于 src/aviationstack_mcp/server.py。
• 所有 MCP 工具都定义为用 @mcp.tool() 装饰的 Python 函数。
• 每个工具都是一个轻量封装：先用 Pydantic 模型校验输入，再调用 对应的普通函数。测试针对的是这些普通函数。
• 该服务使用来自 mcp.server.fastmcp 的 FastMCP 类。mcp 依赖被 固定为 <2，因为 2.x 将 FastMCP 重命名为 MCPServer。
• 工具从不抛出异常。所有失败都会被捕获，并以错误信封的形式返回。

设置并运行 CI 所运行的检查：

uv sync --all-groups

# Unit tests
uv run python -m unittest discover -s tests -v

# Lint, must stay at 10.00/10
uv run pylint $(git ls-files '*.py')

# Coverage
uv run coverage run --source=aviationstack_mcp -m unittest discover -s tests
uv run coverage report

.well-known/mcp/server-card.json 是生成的，而非手动编辑。在更改任何工具、 提示词或资源后，请重新生成它，否则 CI 会失败：

uv run python scripts/generate_server_card.py          # rewrite the card
uv run python scripts/generate_server_card.py --check  # what CI runs

MCP 服务配置

要将此服务添加到您喜欢的 MCP 客户端，您可以将以下内容添加到您的 MCP 客户端配置文件中。

1. 使用 uvx 而无需克隆仓库（推荐）

{
  "mcpServers": {
    "Aviationstack MCP": {
      "command": "uvx",
      "args": [
        "aviationstack-mcp"
      ],
      "env": {
        "AVIATION_STACK_API_KEY": "<your-api-key>"
      }
    }
  }
}

2. 通过克隆仓库并在本地运行服务

{
  "mcpServers": {
    "Aviationstack MCP": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/aviationstack-mcp/src/aviationstack_mcp",
        "run",
        "-m",
        "aviationstack_mcp",
        "mcp",
        "run"
      ],
      "env": {
        "AVIATION_STACK_API_KEY": "<your-api-key>"
      }
    }
  }
}

许可证

本项目依据 MIT 许可证授权。有关详细信息，请参阅 LICENSE。