RepeaterBook

RepeaterBook Python 客户端

非官方项目。 RepeaterBook Python Client 是一个独立、由社区维护的库和 MCP 服务，与 RepeaterBook.com 无关联，未获其认可，也不受其官方支持。“RepeaterBook”是其各自所有者的商标。请访问 https://repeaterbook.com/ 获取官方网站和 API。

欢迎阅读 RepeaterBook Python Client 文档！

RepeaterBook Python Client 是一个非官方的第三方 Python 库，也是 Model Context Protocol（MCP）服务，为 RepeaterBook.com API 提供强大且便捷的接口。该 API 是全球最大的业余无线电中继台数据库。你可以将其用作库，以编程方式下载、查询和分析中继台数据；也可以运行随附的 MCP 服务，为 AI Agent 和大模型工具提供相同的中继台查询能力。

功能

• 便捷访问 API：通过简单的异步接口从 RepeaterBook.com 下载中继台数据
• 非官方 MCP 服务：将中继台同步、地理搜索、查询和清除本地数据作为四个类型化工具提供给任何 MCP 客户端 — 参见 MCP 服务指南
• 本地数据库：将中继台信息存储在本地 SQLite 数据库中，以便快速查询
• 地理查询：通过基于距离的筛选查找某个位置附近的中继台
• 频段筛选：按频率频段查询中继台（2m、70cm 等）
• 数字模式支持：按 DMR、P25、NXDN 和其他数字模式筛选
• 智能缓存：自动缓存 API 响应，以减轻负载并提升性能
• 类型安全：使用 mypy 提供完整类型标注，带来出色的 IDE 支持
• 异步/等待：采用非阻塞 I/O，高效执行 API 操作

快速示例

你需要 RepeaterBook API 令牌。 无需注册应用 — 此库已注册为 RepeaterBook Python Client（应用 #114）。登录 RepeaterBook，打开 API Applications，找到 应用 #114，然后生成令牌。接着将其设为 REPEATERBOOK 环境变量（例如 export REPEATERBOOK="rbuapp_..."）。请保留库的默认 User-Agent — 参见身份验证指南。

import asyncio
import os
from repeaterbook import RepeaterBook, Repeater
from repeaterbook.services import RepeaterBookAPI
from repeaterbook.models import ExportQuery, Status
from repeaterbook.utils import LatLon, Radius
from repeaterbook.queries import filter_radius, square, band, Bands
import pycountry

async def find_nearby_repeaters():
    # Download repeater data
    api = RepeaterBookAPI(app_token=os.environ["REPEATERBOOK"])
    brazil = pycountry.countries.get(name="Brazil")
    repeaters = await api.download(query=ExportQuery(countries={brazil}))

    # Store in local database
    rb = RepeaterBook()
    rb.populate(repeaters)

    # Find DMR repeaters within 50km of São Paulo
    sao_paulo = LatLon(lat=-23.5505, lon=-46.6333)
    radius = Radius(origin=sao_paulo, distance=50)

    nearby = rb.query(
        square(radius),
        Repeater.dmr_capable == True,
        Repeater.operational_status == Status.ON_AIR,
        band(Bands.CM_70)  # 70cm band
    )

    filtered = filter_radius(nearby, radius)

    # Display results (filter_radius returns repeaters sorted by distance)
    from haversine import haversine
    for rep in filtered[:5]:
        distance = haversine(radius.origin, (rep.latitude, rep.longitude), unit=radius.unit)
        print(f"{distance:.1f}km - {rep.frequency:.4f} MHz - {rep.callsign}")

asyncio.run(find_nearby_repeaters())

快速示例（MCP）

想通过 AI Agent 使用 RepeaterBook？非官方 MCP 服务通过 mcp extra 提供 repeaterbook-mcp 控制台脚本。将 MCP 客户端指向 uvx，无需预先安装任何内容：

{
  "mcpServers": {
    "repeaterbook": {
      "command": "uvx",
      "args": ["--from", "repeaterbook[mcp]", "repeaterbook-mcp"],
      "env": {
        "REPEATERBOOK_WORKING_DIR": "~/.repeaterbook",
        "REPEATERBOOK_APP_TOKEN": "rbuapp_..."
      }
    }
  }
}

REPEATERBOOK_APP_TOKEN 是上文所述的同一个 应用 #114 令牌；没有该令牌， 服务将无法启动。

这会提供四个工具：sync_repeaters、search_repeaters 和 get_repeater，它们会返回稳定且与数据来源无关的中继台规范；此外还有 clear_local_data，用于清除本地存储和响应缓存。完整的工具参考、筛选词汇 和配置选项，请参见 MCP 服务指南。

文档

• 入门指南 - 面向初学者的教程
• 使用指南 - 全面的使用示例
• MCP 服务 - 运行供 AI Agent 使用的非官方 MCP 服务
• 示例 - 真实使用场景
• 架构 - 了解内部实现
• API 参考 - 完整的 API 文档
• 常见问题 - 常见问题与故障排除

阅读完整文档

如需了解有关上游 API 的更多信息，请阅读 RepeaterBook.com 的官方 API 文档。

使用场景

• AI Agent 和助手：让大模型通过 MCP 以对话方式查询中继台
• 行程规划：查找沿途的中继台
• 应急通信：识别支持应急通信的中继台
• 无线电编程：为 DMR 和其他数字无线电生成 codeplug
• 覆盖范围分析：创建覆盖地图和统计数据
• 网络分析：分析中继台网络和基础设施
• 移动应用：构建中继台目录应用
• 研究：分析业余无线电中继台的趋势和分布

相关项目

• MicaelJarniac/opengd77 - OpenGD77 无线电编程
• MicaelJarniac/ogdrb - OpenGD77 与 RepeaterBook 集成

另请参阅

• afourney/hamkit - 业余无线电工具包
• desertblade/OpenGD77-Repeaterbook - OpenGD77 集成
• TomHW/OpenGD77 - OpenGD77 固件

安装

PyPI

repeaterbook 可在 PyPI 上获取：

# With uv (recommended)
uv add repeaterbook

# With pip
pip install repeaterbook

# With Poetry
poetry add repeaterbook

MCP 服务

MCP 服务位于 mcp extra 中。大多数 MCP 客户端应通过 uvx 调用它， 无需执行安装步骤：

# Run on demand, no install (what MCP clients should use)
uvx --from "repeaterbook[mcp]" repeaterbook-mcp

# Or install it persistently
uv tool install "repeaterbook[mcp]"

# Or add it as a project dependency
uv add "repeaterbook[mcp]"
pip install "repeaterbook[mcp]"

GitHub

你也可以直接从 GitHub 安装最新版本的代码：

# With uv
uv add git+https://github.com/MicaelJarniac/repeaterbook

# With pip
pip install git+https://github.com/MicaelJarniac/repeaterbook

# With Poetry
poetry add git+https://github.com/MicaelJarniac/repeaterbook

要求

• Python 3.11 或更高版本
• 依赖项会自动安装：
  • aiohttp - 异步 HTTP 客户端
  • anyio - 异步兼容层
  • attrs - 不可变配置类
  • haversine - 距离计算
  • loguru - 结构化日志
  • pycountry - 国家／地区代码
  • pydantic - 数据验证
  • sqlmodel - 具备类型安全的 SQL ORM
  • tqdm - 进度条
  • yarl - URL 处理
• 可选的 mcp extra 还会安装 fastmcp、pydantic-settings 和 pydantic[email]（用于 EmailStr 联系方式设置）

贡献

欢迎提交拉取请求。对于重大更改，请先提出 issue，讨论你希望进行的更改。

请确保酌情更新测试。

更多详情请参阅 CONTRIBUTING。

贡献者 ✨

Micael Jarniac 🐛 💻 🖋 🔣 📖 💡 🤔 🚇 🚧 📆 💬 🔬 👀 🔧 ⚠️ 📓

ada mancini 🐛 🤔 📓

aaronjbrown 💻 📖 🤔 ⚠️

Erica Morton 🐛 💻 📖 🔬 ⚠️

许可证

MIT

本项目基于 MicaelJarniac/crustypy 模板创建。