使用说明

航空MCP服务器

一个通过ADS-B Exchange（adsb.lol API）提供实时飞机数据的FastMCP服务器 可流式传输的HTTP传输。

特点/特性

🚀 火箭或快速前进的象征（通常用于表示科技、进步或速度） 可流式传输的HTTP传输 - 使用JSON-RPC协议的现代HTTP
🔐（锁形符号，常用于表示保密、安全或密码等含义） API密钥认证 - 安全访问控制
⚡（闪电符号，常用于表示速度、活力或电力） FastMCP 框架 - 高性能MCP服务器
🛫（飞机起飞） 实时飞机数据 - 来自adsb.lol的实时ADS-B数据
📡（天线/卫星天线/无线电信标） 多种查询类型 - 8种不同的查询飞机数据的方式
🐳 表示“海豚”或“水瓶座（星座）”，在中文里可以直接用“海豚”或“水瓶座”来表达这个表情符号的含义。 已准备好投入生产 - 可以独立运行或在容器中运行

快速入门

安装

cd aviation-mcp-server
uv sync

运行服务器

开发：

uv run aviation-mcp-server-http

带有自定义配置：

export MCP_HOST="0.0.0.0"
export MCP_PORT="8000"
export MCP_API_KEY="your-secret-key"
uv run aviation-mcp-server-http

服务器将在 http://0.0.0.0:8000/mcp

配置

环境变量：

MCP_HOST=0.0.0.0                          # Server bind address (default: 0.0.0.0)
MCP_PORT=8000                             # Server port (default: 8000)
MCP_API_KEY=your-secret-key               # API key for authentication (default: dev key)

API 文档

终端节点

统一资源定位符（URL）： http://localhost:8000/mcp
方法POST（网络请求方法）
内容类型: application/json
接受: application/json, text/event-stream

认证

请将API密钥包含在以下标头之一中：

X-API-Key: your-secret-key
Authorization: Bearer your-secret-key

可用工具： `query_aircraft`

从ADS-B Exchange查询实时飞机数据。

参数

查询类型 （必填）：查询类型
- "callsign"按航班呼号搜索（例如，“UAL123”）
- "registration"按飞机注册号搜索（例如，“N12345”）
- "aircraft_type"按飞机类型搜索（例如，“B738”，“A320”）
- "icao_hex"按国际民航组织（ICAO）六位代码搜索
- "squawk"按应答机编码（例如，“7700”）搜索
- "location"在坐标半径范围内搜索
- "military"获取所有军用飞机
- "privacy"获取具有隐私保护的国际民航组织（ICAO）地址的飞机
价值（可选）：大多数查询类型的搜索值
纬度（可选）：用于位置查询的纬度（-90 到 90）
经度（可选）：用于位置查询的经度（-180 至 180）
半径（可选）：位置查询时的搜索半径（以海里为单位）

示例请求

列出可用工具：

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-API-Key: adsb-mcp-secret-key-change-in-production" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

查询军用飞机：

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-API-Key: adsb-mcp-secret-key-change-in-production" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "query_aircraft",
      "arguments": {
        "query_type": "military"
      }
    }
  }'

按呼号查询：

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-API-Key: adsb-mcp-secret-key-change-in-production" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "query_aircraft",
      "arguments": {
        "query_type": "callsign",
        "value": "UAL123"
      }
    }
  }'

按位置查询：

curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-API-Key: adsb-mcp-secret-key-change-in-production" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "query_aircraft",
      "arguments": {
        "query_type": "location",
        "latitude": 40.7128,
        "longitude": -74.0060,
        "radius": 50
      }
    }
  }'

测试

测试服务器连接性

uv run python test_server.py

这将：

测试军用飞机查询
测试呼号查询
验证API连接性

手动健康检查

curl -I http://localhost:8000/mcp

预期： 405 Method Not Allowed (GET 不受支持，请使用 POST)

集成

Discord 机器人

这个（或“该”） aviation-discord-bot 项目可以连接到此服务器：

MCP_TRANSPORT=http
MCP_SERVER_URL=http://localhost:8000/mcp
MCP_API_KEY=your-secret-key

克劳德桌面版

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

{
  "mcpServers": {
    "adsb-aircraft-data": {
      "command": "bash",
      "args": ["-c", "cd /path/to/aviation-mcp-server && uv run aviation-mcp-server-http"],
      "env": {
        "MCP_API_KEY": "your-secret-key"
      }
    }
  }
}

其他MCP客户端

任何支持HTTP传输的MCP客户端都可以使用以下方式连接：

交通HTTP
URL（统一资源定位符）: http://localhost:8000/mcp
协议；议定书JSON-RPC 2.0
认证通过API密钥 X-API-Key 头球

建筑

┌────────────────┐
│  MCP Client    │
│  (Bot/Claude)  │
└────────┬───────┘
         │
         │ HTTP POST + JSON-RPC
         │ + X-API-Key header
         │
         ▼
┌────────────────┐
│  FastMCP       │
│  + uvicorn     │
│  + Auth        │
└────────┬───────┘
         │
         │ HTTPS
         │
         ▼
┌────────────────┐
│  adsb.lol API  │
│  (ADS-B Data)  │
└────────────────┘

部署

Docker

FROM python:3.12-slim
WORKDIR /app
COPY . .
RUN pip install uv && uv sync
ENV MCP_API_KEY=${MCP_API_KEY}
ENV MCP_HOST=0.0.0.0
ENV MCP_PORT=8000
EXPOSE 8000
CMD ["uv", "run", "aviation-mcp-server-http"]

构建并运行：

docker build -t aviation-mcp-server .
docker run -p 8000:8000 -e MCP_API_KEY=your-secret-key aviation-mcp-server

Kubernetes（通常简称为K8s）

apiVersion: apps/v1
kind: Deployment
metadata:
  name: aviation-mcp-server
spec:
  replicas: 2
  selector:
    matchLabels:
      app: aviation-mcp-server
  template:
    metadata:
      labels:
        app: aviation-mcp-server
    spec:
      containers:
      - name: server
        image: aviation-mcp-server:latest
        ports:
        - containerPort: 8000
        env:
        - name: MCP_API_KEY
          valueFrom:
            secretKeyRef:
              name: mcp-secrets
              key: api-key
---
apiVersion: v1
kind: Service
metadata:
  name: aviation-mcp-server
spec:
  selector:
    app: aviation-mcp-server
  ports:
  - port: 80
    targetPort: 8000
  type: LoadBalancer

systemd 服务

创建 /etc/systemd/system/aviation-mcp-server.service:

[Unit]
Description=Aviation MCP Server
After=network.target

[Service]
Type=simple
User=adsb
WorkingDirectory=/opt/aviation-mcp-server
Environment="MCP_API_KEY=your-secret-key"
Environment="MCP_HOST=0.0.0.0"
Environment="MCP_PORT=8000"
ExecStart=/usr/local/bin/uv run aviation-mcp-server-http
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

启用并启动：

sudo systemctl enable aviation-mcp-server
sudo systemctl start aviation-mcp-server
sudo systemctl status aviation-mcp-server

安全

生产建议

使用HTTPS在反向代理（nginx、Caddy）后部署，并启用TLS
安全API密钥使用密钥管理服务（AWS Secrets Manager，HashiCorp Vault）
速率限制实施速率限制以防止滥用
监测添加日志记录和指标监控（Prometheus、Grafana）
IP过滤限制访问已知客户端IP
定期更新保持依赖项更新

Nginx 配置示例

upstream adsb_mcp {
    server 127.0.0.1:8000;
}

server {
    listen 443 ssl http2;
    server_name mcp.example.com;

    ssl_certificate /etc/ssl/certs/mcp.crt;
    ssl_certificate_key /etc/ssl/private/mcp.key;

    location /mcp {
        proxy_pass http://adsb_mcp;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Rate limiting
        limit_req zone=mcp_limit burst=10 nodelay;
    }
}

故障排除

服务器无法启动

检查端口8000是否已被占用： lsof -i :8000
验证依赖项： uv sync
检查Python版本： python --version （需要3.10及以上版本）

认证错误

在请求头中验证API密钥
检查服务器日志以查找身份验证失败
确保API密钥匹配 MCP_API_KEY 环境变量

API错误

验证与adsb.lol的互联网连接是否正常
检查adsb.lol API的状态
检查服务器日志以获取错误详情

性能问题

监控服务器资源（CPU、内存）
检查adsb.lol API的网络延迟
考虑实施缓存机制

发展

项目结构

aviation-mcp-server/
├── src/
│   └── aviation_mcp_server/
│       ├── __init__.py
│       └── server.py          # Main server implementation
├── pyproject.toml             # Dependencies
├── .python-version            # Python version (3.12)
├── README.md                  # This file
└── test_server.py             # Connectivity tests

添加新工具

要添加一个新的MCP工具，请编辑 server.py：

@mcp.tool()
async def your_new_tool(param1: str, param2: int) -> str:
    """
    Description of your tool.

    Args:
        param1: Description
        param2: Description

    Returns:
        Result description
    """
    # Implementation
    return "result"

运行测试

# Test server connectivity
uv run python test_server.py

# Manual API test
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-API-Key: adsb-mcp-secret-key-change-in-production" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

API数据源

这台服务器使用的是 “adsb.lol”可以翻译为“ADS-B（广播式自动相关监视）. lol（哈哈，开玩笑啦）”。不过，通常“lol”在网络语境中直接表达“哈哈”的意思，但在这里为了保持原句的格式，可以稍作调整，翻译为“ADS-B（广播式自动相关监视）. 哈哈（开玩笑啦）”。不过，具体翻译还需根据上下文和语境来判断 API，其提供：

实时飞机位置
飞行信息（呼号、高度、速度）
飞机详情（机型、注册号）
军用飞机追踪
全球覆盖

许可证

麻省理工学院（MIT）

贡献；做出贡献

欢迎投稿！请：

为仓库创建分支（或：克隆仓库）
创建一个特性分支
做出你的更改
如适用，请添加测试
提交一个拉取请求

支持

对于问题或疑问：

查阅故障排除部分
检查服务器日志
使用手动curl请求进行测试
验证环境变量