RepeaterBook Python Client¶

Unofficial project. RepeaterBook Python Client is an independent, community-maintained library and MCP server, and is not affiliated with, endorsed by, or officially supported by RepeaterBook.com. "RepeaterBook" is a trademark of its respective owner. For the official website and API, visit https://repeaterbook.com/.

Welcome to the RepeaterBook Python Client documentation!

RepeaterBook Python Client is an unofficial, third-party Python library and Model Context Protocol (MCP) server that provides a powerful and convenient interface to the RepeaterBook.com API — the world's largest database of amateur radio repeaters. Use it as a library to programmatically download, query, and analyze repeater data, or run the bundled MCP server to give AI agents and LLM tools the same repeater lookup capabilities.

Features¶

Easy API Access: Download repeater data from RepeaterBook.com with a simple async interface
Unofficial MCP Server: Ship repeater sync, geographic search, and lookup to any MCP client as three typed tools — see the MCP Server guide
Local Database: Store repeater information in a local SQLite database for fast queries
Geographic Queries: Find repeaters near a location using distance-based filtering
Band Filtering: Query repeaters by frequency band (2m, 70cm, etc.)
Digital Mode Support: Filter by DMR, P25, NXDN, and other digital modes
Smart Caching: Automatic caching of API responses to reduce load and improve performance
Type Safe: Fully typed with mypy for excellent IDE support
Async/Await: Non-blocking I/O for efficient API operations

Quick Example¶

You need a RepeaterBook API token. No application registration required — this library is already registered as RepeaterBook Python Client (App #114). Log in to RepeaterBook, open API Applications, find App #114, and generate a token. Then expose it as the REPEATERBOOK environment variable (for example export REPEATERBOOK="rbuapp_..."). Keep the library's default User-Agent — see the Authentication guide.

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())

Quick Example (MCP)¶

Prefer to drive RepeaterBook from an AI agent? The unofficial MCP server ships as the repeaterbook-mcp console script behind the mcp extra. Point your MCP client at uvx and nothing needs installing up front:

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

REPEATERBOOK_APP_TOKEN is the same App #114 token described above; the server won't start without it.

That exposes three tools — sync_repeaters, search_repeaters, and get_repeater — returning a stable, source-agnostic repeater spec. See the MCP Server guide for the full tool reference, filter vocabulary, and configuration options.

Documentation¶

Getting Started - Tutorial for beginners
Usage Guide - Comprehensive usage examples
MCP Server - Run the unofficial MCP server for AI agents
Examples - Real-world use cases
Architecture - Understanding the internals
API Reference - Complete API documentation
FAQ - Common questions and troubleshooting

Read the full documentation

Read RepeaterBook.com's official API documentation for more information about the upstream API.

Use Cases¶

AI Agents & Assistants: Let an LLM look up repeaters conversationally over MCP
Trip Planning: Find repeaters along travel routes
Emergency Communications: Identify emergency-capable repeaters
Radio Programming: Generate codeplugs for DMR and other digital radios
Coverage Analysis: Create coverage maps and statistics
Network Analysis: Analyze repeater networks and infrastructure
Mobile Apps: Build repeater directory applications
Research: Analyze amateur radio repeater trends and distributions

MicaelJarniac/opengd77 - OpenGD77 radio programming
MicaelJarniac/ogdrb - OpenGD77 RepeaterBook integration

Installation¶

PyPI¶

repeaterbook is available on PyPI:

# With uv (recommended)
uv add repeaterbook

# With pip
pip install repeaterbook

# With Poetry
poetry add repeaterbook

MCP server¶

The MCP server lives behind the mcp extra. Most MCP clients should invoke it via uvx, with no install step at all:

# 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¶

You can also install the latest version of the code directly from 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

Requirements¶

Python 3.11 or higher
Dependencies are automatically installed:
aiohttp - Async HTTP client
anyio - Async compatibility layer
attrs - Immutable config classes
haversine - Distance calculations
loguru - Structured logging
pycountry - Country/region codes
pydantic - Data validation
sqlmodel - SQL ORM with type safety
tqdm - Progress bars
yarl - URL handling
The optional mcp extra additionally installs fastmcp, pydantic-settings, and pydantic[email] (for the EmailStr contact setting)