AI导哈

飞机追踪服务

该服务通过集成airplanes.live API，提供实时飞机追踪功能，支持通过呼号、注册号或位置搜索飞机，适用于教育和非商业用途。

  • by Bellaposa
  • Python
  • 本地部署
  • 9 星标
  • 更新于
在 GitHub 查看 Bellaposa/airplanes-live-mcp

使用说明

✈️ 飞机跟踪器MCP服务器

🎯 概述

此MCP服务器与 空中航线直播API 为Claude Desktop提供实时飞机跟踪功能。追踪航班，通过呼号、注册或位置找到飞机——所有这些都可以直接从克劳德那里获得！

⚠️ 重要通知-使用条款

📖 仅供教育和非商业用途

该项目使用 空中航线直播API 这是为 仅用于教育和非商业目的请尊重他们的服务条款。

📋 使用指南：

  • ✅ 教育项目 -学习和研究
  • ✅ 个人使用 -非商业追踪
  • ✅ 开源贡献 -社区发展
  • ❌ 商业应用 -商业/盈利目的
  • ❌ 大量请求 -遵守费率限制

🛡️ 免责声明：

此MCP服务器的作者对使用此软件不承担任何责任。 这是一份旨在用于教育目的和演示MCP服务器开发的社区贡献。用户有责任遵守API直播条款和任何适用法规。

🌐 尊重现有服务：

该项目无意取代或与官方竞争 飞机.全球实况观众. 官方地球仪是可视化飞行数据的主要和推荐方式。此MCP服务器被设计为Claude Desktop集成和MCP开发学习的补充教育工具。

📖 API完整条款: https://airplanes.live/api-guide/
🌍 官方环球查看器: https://globe.airplanes.live

📸 截图

Claude Desktop中的实时飞机跟踪

🚀 特性

  • 🔍 按呼号搜索 -查找特定航班（例如UAL123）
  • 📋 注册查询 -按尾号跟踪（例如N12345）
  • 🎯 基于职位的搜索 -坐标附近的飞机
  • 🏷️ 十六进制ID搜索 -S模式应答机代码
  • 🛡️ 军用飞机 -跟踪军事飞行
  • 🚁 LADD飞机 -执法追踪
  • ⭐ PIA飞机 -私人/有趣的飞机
  • 📡 Squawk代码 -紧急和特殊代码

各种API搜索示例

🏗️ 建筑

🔧 组件

  • 🐍 Python MCP服务器 -异步服务器实现
  • 🌐 MCP框架 -现代服务器架构
  • ⚡ httpx客户端 -高性能HTTP请求
  • 📊 数据格式化程序 -清晰易读的飞机信息
  • 🔌 克劳德集成 -直接MCP协议支持

📊 数据流

graph TD
    A[Claude Desktop] --> B[MCP Protocol]
    B --> C[airplane_server.py]
    C --> D[API Functions]
    D --> E[airplanes.live API]
    E --> F[Aircraft Data]
    F --> G[Formatted Response]
    G --> A

系统架构和数据流

🚀 快速开始

📋 先决条件

  • 🐍 Python 3.8+
  • 💻 克劳德桌面版
  • 🌐 Internet连接

⚡ 安装

# 1. Clone the repository
git clone https://github.com/Bellaposa/airplanes-live-mcp.git
cd airplanes-live-mcp

# 2. Create virtual environment (REQUIRED!)
python -m venv .venv

# 3. Activate virtual environment
# macOS/Linux:
source .venv/bin/activate
# Windows:
.venv\Scripts\activate

# 4. Install dependencies
pip install -r requirements.txt

# 5. Test the server
python airplane_server.py

⚠️ 常见问题及解决方案

🔥 虚拟环境是必须的！

  • 如果你跳过步骤2-3，你会得到 ModuleNotFoundError: No module named 'httpx'
  • 克劳德桌面需要 完整路径 使用venv Python，而不是系统Python
  • 没有venv，依赖关系就不会孤立，事情也会破裂

🪟 Windows用户：

  • 虚拟环境创建 .venv\Scripts\ 文件夹（不是 .venv\bin\)
  • 使用 Scripts\python.exe 在Claude配置中，不是 bin/python
  • 始终使用双反睫毛 \\ JSON路径中

🐍 Python路径问题：

  • 请确保已安装Python 3.8+： python --version
  • 如果 python 不起作用，试试看 python3 或 py
  • 配置Claude Desktop之前，虚拟环境必须存在

🐳 Docker安装（替代方案）

跳过Python设置的麻烦——改用Docker！

📋 先决条件

  • 🐳 Docker桌面已安装并正在运行
  • 💻 克劳德桌面版

⚡ Docker设置

# 1. Clone the repository
git clone https://github.com/Bellaposa/airplanes-live-mcp.git
cd airplanes-live-mcp

# 2. Build Docker image
docker build -t airplane-mcp-server .

# 3. Test the container
docker run --rm -it airplane-mcp-server python airplane_server.py

⚙️ Docker的Claude桌面配置

🍎 macOS/Linux与Docker

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

{
  "mcpServers": {
    "airplanes-live": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", 
        "airplane-mcp-server", 
        "python", "airplane_server.py"
      ]
    }
  }
}

🪟 Windows与Docker

添加到 %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "airplanes-live": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", 
        "airplane-mcp-server", 
        "python", "airplane_server.py"
      ]
    }
  }
}

🔄 Docker命令参考

# Build the image
docker build -t airplane-mcp-server .

# Run interactively for testing
docker run --rm -it airplane-mcp-server bash

# Check if image exists
docker images | grep airplane-mcp-server

# Remove image if needed
docker rmi airplane-mcp-server

# View container logs (if running detached)
docker logs <container_id>

✅ Docker优势

  • 🚀 无需Python设置 -所有内容均已预先配置
  • 🔒 孤立的环境 -无依赖冲突
  • 🌍 适用于所有地方 -Windows/Mac/Linux上的设置相同
  • 📦 轻松更新 -只需重建图像
  • 🛡️ 一致性行为 -消除“在我的机器上工作”

⚠️ Docker故障排除

问题：“docker：找不到命令”

# Install Docker Desktop first
# macOS: https://docs.docker.com/desktop/install/mac-install/
# Windows: https://docs.docker.com/desktop/install/windows-install/
# Linux: https://docs.docker.com/desktop/install/linux-install/

问题：“无法连接到Docker守护进程”

# Start Docker Desktop application
# Wait for Docker to fully start (green icon)

问题：“权限被拒绝”（Linux）

# Add user to docker group
sudo usermod -aG docker $USER
# Log out and back in, or:
newgrp docker

问题：映像构建失败

# Clean Docker cache
docker system prune -a
# Try building again
docker build --no-cache -t airplane-mcp-server .

🎯 更简单：Docker Compose

对于最简单的设置，请使用Docker Compose：

# 1. Clone and enter directory
git clone https://github.com/Bellaposa/airplanes-live-mcp.git
cd airplanes-live-mcp

# 2. Build and run with one command
docker-compose up --build

# 3. In another terminal, test the server
docker-compose exec airplane-mcp-server python airplane_server.py

Docker编写克劳德配置：

{
  "mcpServers": {
    "airplanes-live": {
      "command": "docker-compose", 
      "args": [
        "-f", "/path/to/airplanes-live-mcp/docker-compose.yml",
        "exec", "-T", "airplane-mcp-server", 
        "python", "airplane_server.py"
      ],
      "cwd": "/path/to/airplanes-live-mcp"
    }
  }
}

🐳 如何使用Claude Desktop

方法1：简单的Docker运行

所有平台的配置：

{
  "mcpServers": {
    "airplanes-live": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i", 
        "airplane-mcp-server", 
        "python", "airplane_server.py"
      ]
    }
  }
}

方法2：Docker编写（高级）

具有完整路径的配置：

{
  "mcpServers": {
    "airplanes-live": {
      "command": "docker-compose",
      "args": [
        "-f", "/full/path/to/your/airplanes-live-mcp/docker-compose.yml",
        "exec", "-T", "airplane-mcp-server", 
        "python", "airplane_server.py"
      ],
      "cwd": "/full/path/to/your/airplanes-live-mcp"
    }
  }
}

完成Docker设置步骤：

# 1. Clone and build
git clone https://github.com/Bellaposa/airplanes-live-mcp.git
cd airplanes-live-mcp
docker build -t airplane-mcp-server .

# 2. Configure Claude Desktop with Method 1 (above)

# 3. Restart Claude Desktop completely

# 4. Test with: "Show me aircraft near New York"

🎯 Docker与Python的比较：

方法 优点 缺点 最适合
码头工人 ✅ 无Python设置
✅ 适用于所有地方
✅ 孤立		 ❌ 需要Docker
❌ 轻微开销		 初学者、Windows用户
python ✅ 直接执行
✅ 易于调试
✅ 不需要Docker❌ 手动Python设置
❌ 操作系统特定问题		 开发人员、经验丰富的用户

Docker编写命令：

# Start services in background
docker-compose up -d

# View logs
docker-compose logs airplane-mcp-server

# Stop services
docker-compose down

# Rebuild and restart
docker-compose up --build


### ⚙️ Claude Desktop Configuration

#### 🍎 **macOS/Linux Configuration**

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `~/.config/claude-desktop/config.json` (Linux):

```json
{
  "mcpServers": {
    "airplanes-live": {
      "command": "/path/to/airplanes-live-mcp/.venv/bin/python",
      "args": ["/path/to/airplanes-live-mcp/airplane_server.py"],
      "env": {
        "PYTHONPATH": "/path/to/airplanes-live-mcp"
      }
    }
  }
}

🪟 Windows配置

添加到 %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "airplanes-live": {
      "command": "C:\\Users\\YourUsername\\airplanes-live-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\Users\\YourUsername\\airplanes-live-mcp\\airplane_server.py"],
      "env": {
        "PYTHONPATH": "C:\\Users\\YourUsername\\airplanes-live-mcp"
      }
    }
  }
}

⚠️ Windows重要注意事项：

  • 使用 Scripts\\python.exe （不是 bin/python)
  • 替换 YourUsername 使用您的实际Windows用户名
  • 使用双反睫毛 \\ 在路径
  • 确保虚拟环境是通过以下方式创建的 python -m venv .venv

Claude桌面配置

🎮 使用示例

按呼号搜索

🔍 Find flight UAL123

近位置搜索

📍 Show aircraft near 40.7128, -74.0060 within 50nm

军用飞机

🛡️ Show all military aircraft

🔧 关键设计决策

1.异步实现

所有工具使用 async 为了高效地处理多个请求：

@mcp.tool()
async def aircraft_near_position(latitude: str = "", longitude: str = "", radius: str = "250") -> str:

这允许服务器在不阻塞的情况下处理并发请求。

2.基于字符串的参数

所有参数都是字符串，因为MCP协议最适合简单类型：

# Correct
def tool(param: str = "") -> str:

# Avoid
def tool(param: Optional[int] = None) -> str:

3.错误处理

每个工具都包括全面的错误处理：

try:
    # Main logic
except ValueError:
    return f"❌ Error: Invalid input"
except Exception as e:
    return f"❌ Error: {str(e)}"

4.数据格式

这 format_aircraft_data() 函数提供一致、可读的输出：

def format_aircraft_data(aircraft_data):
    # Handles both single aircraft and lists
    # Formats all available fields with emoji indicators
    # Returns human-readable strings

5.API包装

这 make_api_request() 函数集中了HTTP逻辑：

async def make_api_request(endpoint):
    async with httpx.AsyncClient(timeout=15) as client:
        url = f"{API_BASE_URL}{endpoint}"
        response = await client.get(url)
        response.raise_for_status()
        return response.json()

这种方法：

  • 集中错误处理
  • 管理超时
  • 记录所有请求
  • 便于以后添加身份验证

工具参考

aircraft_by_hex（hex-id:str=“”）

目的：通过S模式十六进制标识符搜索飞机

输入：逗号分隔的十六进制ID（例如，“45211e，45212f”）

退货：完整详细的匹配飞机清单

示例:

User: "Show me aircraft with hex 45211e"
Tool: "🔍 Found 1 aircraft: ✈️ Callsign: RYR123 ..."

aircraft _ _呼号（呼号：str=“”）

目的：通过航班呼号搜索飞机

输入：逗号分隔的呼号（例如“BA387、AA123”）

退货：与呼号匹配的飞机

示例:

User: "Find flight BA387"
Tool: "🔍 Found 1 aircraft: ✈️ Callsign: BA387 ..."

飞机_ _注册（reg:str=“”）

目的：按机尾号/登记搜索飞机

输入：逗号分隔的注册（例如“N123AB，g-EUPA”）

退货：与登记相符的飞机

示例:

User: "Show aircraft with tail N123AB"
Tool: "🔍 Found 1 aircraft: 📋 Registration: N123AB ..."

飞机类型（icao_type:str=“”）

目的：按国际民航组织类型代码搜索飞机

输入：型号代码（A321、B738、C172、E190等）

退货：目前正在飞行的所有此类飞机

示例:

User: "Show all Boeing 737s"
Tool: "🔍 Found 247 aircraft of type B738: ..."

飞机_by_squawk（squawk_code:str=“”）

目的：按叫声代码搜索飞机

输入：4位squawk代码（例如，“7500”、“7600”、“7700”）

退货：飞机发出那个代码

备注：7700=紧急情况，7600=通信故障，7500=劫持

示例:

User: "Find aircraft squawking 7700"
Tool: "🔍 Found aircraft in emergency: ..."

aircraft_near_position（纬度：str=“”，经度：str=

目的：查找坐标半径内的所有飞机

输入:

  • 纬度（十进制度数，-90到90）
  • 经度（十进制度数，-180到180）
  • 半径（海里，最大250）

退货：半径内的所有飞机

示例:

User: "Show aircraft within 50 nm of Madrid (40.4168, -3.7038)"
Tool: "📍 Found 23 aircraft within 50 nm of 40.4168, -3.7038: ..."

军用飞机

目的：列出所有军用飞机

输入：无

退货：所有标记为军用的飞机

示例:

User: "What military aircraft are flying?"
Tool: "🎖️ Found 12 military aircraft: ..."

激光飞机（）

目的：列出执法和安保飞机

输入：无

退货：所有LADD（执法/安全）飞机

示例:

User: "Show law enforcement aircraft"
Tool: "🚁 Found 8 LADD aircraft: ..."

pia_aircraft（）

目的：列出有趣/特殊的飞机

输入：无

退货：所有PIA（特殊利益）飞机

示例:

User: "Show special/private aircraft"
Tool: "🛡️ Found 156 PIA aircraft: ..."

输出格式

所有工具都返回带表情符号指示符的格式化字符串：

✈️ Callsign: BA387
📋 Registration: G-EUPA
🛩️ Type: A350
📍 Position: 51.4769, -0.4589
📏 Altitude: 35000 ft
⚡ Ground Speed: 485 knots
🧭 Track: 089°
🔖 Mode S Hex: 406ee9
👁️ Last Seen: 3 seconds ago

这提供了：

  • 表情符号的视觉清晰度
  • 轻松扫描信息
  • 格式一致
  • 专业形象

添加新工具

要向此服务器添加新工具，请执行以下操作：

步骤1：创建工具函数

@mcp.tool()
async def new_tool(param1: str = "", param2: str = "") -> str:
    """Single-line description of what this tool does."""
    if not param1.strip():
        return "❌ Error: param1 is required"
    
    try:
        # Your implementation
        result = await make_api_request("/endpoint")
        formatted = format_aircraft_data(result.get('ac', []))
        return f"✅ Success:\n\n{formatted}"
    except Exception as e:
        return f"❌ Error: {str(e)}"

步骤2：添加到目录

更新 tools: custom.yaml中的部分：

tools:
  - name: new_tool

步骤3：重建Docker镜像

docker build -t airplane-mcp-server .

步骤4:重新启动克劳德桌面

新工具将自动出现。

测试

单元测试模式

import asyncio

async def test_aircraft_by_callsign():
    result = await aircraft_by_callsign("BA387")
    assert "✈️" in result
    assert "Found" in result
    print(result)

# Run with: asyncio.run(test_aircraft_by_callsign())

集成测试

# Start server
python airplane_server.py

# In another terminal, test via stdin:
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | python airplane_server.py

性能注意事项

API响应时间

  • 典型值：500ms-1s
  • 复杂查询：1s-2s
  • 超时：15秒

数据限制

  • 每次查询最多1000架飞机（API限制）
  • 半径搜索：最大250海里
  • 呼号/注册：逗号分隔，最多8000个字符

优化提示

  1. 使用特定搜索 -窄搜索更快
  2. 避免敲打API -合理的请求频率
  3. 在本地缓存结果 -考虑存储最近的查询
  4. 监视器超时 -API在高峰流量期间可能较慢

故障排除指南

问题：工具不出现

解决方案:

  1. 验证已构建的映像： docker images | grep airplane
  2. 检查目录： cat ~/.docker/mcp/catalogs/custom.yaml
  3. 验证注册表： cat ~/.docker/mcp/registry.yaml
  4. 重启克劳德：完全退出，然后重新打开

问题：“未找到飞机”

原因:

  • 坐标错误（验证lat/lon格式）
  • 半径太小
  • 那个地区没有交通
  • 类型代码错误（请尝试大写）

解决方案：尝试更广泛的搜索或不同的参数

问题：API超时

原因：API速度缓慢或速率受限

解决方案:

  • 等待30秒
  • 尝试更简单的查询
  • 检查互联网连接

问题：Docker权限被拒绝

解决方案:

# Add user to docker group
sudo usermod -aG docker $USER
# Log out and back in
newgrp docker

🗺️ 未来的增强功能

⚠️ 重要提示：此计划中的仪表板旨在作为 教育补充 致优秀官员 飞机.全球实况观众，而不是替代品。目标是演示web开发与MCP服务器的集成，以供学习。

  • [ ] 缓存系统 -Redis缓存可减少API调用
  • [ ] 速率限制 -智能请求限制
  • [ ] 导出功能 -将结果保存为JSON/CSV/KML格式
  • [ ] 增强格式 -Claude中更好的数据可视化
  • [ ] 航班警报 -特定飞机出现时通知
  • [ ] 历史跟踪 -存储和跟踪飞机动态
  • [ ] 统计仪表板 -汇总数据和分析
  • [ ] API扩展 -额外的飞机。实时端点

🤖 AI驱动的功能

  • 🧠 飞行预报 -基于ML的飞行路径估计
  • 📈 模式分析 -识别异常飞行模式
  • 🚨 异常检测 -针对有趣事件的自动警报
  • 📊 趋势分析 -历史数据洞察

安全

当前方法

  • 无需身份验证（公共API数据）
  • 考虑申请API密钥用于生产
  • 未存储敏感凭据
  • 以非root用户身份运行
  • 所有参数的输入验证

未来的考虑因素

  • 如果需要，添加速率限制
  • 实施查询日志记录以进行监控
  • 考虑缓存以减少API调用
  • 为自定义端点添加输入净化

📚 资源

  • API文档: https://airplanes.live/
  • API使用条款: https://airplanes.live/api-guide/
  • MCP规范: https://docs.anthropic.com/mcp
  • FastMCP文档: https://github.com/jlowin/fastmcp
  • httpx文档: https://www.python-httpx.org/

🤝 贡献

这是一个开源教育项目！欢迎捐款：

  • 🐛 错误报告 -打开一个问题
  • 💡 功能请求 -提出改进建议
  • 🔧 拉取请求 -提交代码更改
  • 📖 文档 -改进指南和示例

📄 许可与免责声明

MIT许可证 -您可以出于教育目的自由使用、修改和分发。

⚖️ 法律声明：

  • 本软件按“原样”提供，不提供保修
  • 作者对使用或合规性不承担任何责任
  • 用户必须遵守API实时条款
  • 仅用于教育和非商业用途
  • 不隶属于航空公司。live

🎯 项目意图：

这个项目是 社区贡献 用于教育目的，演示MCP服务器开发和API集成。目标是帮助开发人员学习并为MCP生态系统做出贡献，而不是为了商业利益。

由...制作❤️ 对于MCP社区 ✈️

记住：始终尊重API条款并负责任地使用！

相关 MCP