{
  "markdown": "<!-- mcp-name: io.github.qso-graph/qrz-mcp -->\n# qrz-mcp\n\nMCP server for [QRZ.com](https://www.qrz.com/) — callsign lookups, DXCC entity resolution, and logbook queries through any MCP-compatible AI assistant.\n\nPart of the [qso-graph](https://qso-graph.io/) project. Uses [qso-graph-auth](https://pypi.org/project/qso-graph-auth/) for credential management.\n\n## Install\n\n```bash\npip install qrz-mcp\n```\n\n## Tools\n\n| Tool | API | Auth | Description |\n|------|-----|------|-------------|\n| `qrz_lookup` | XML | Session key | Callsign lookup (name, grid, DXCC, license class, QSL info, image) |\n| `qrz_dxcc` | XML | Session key | DXCC entity resolution from callsign or entity code |\n| `qrz_logbook_status` | Logbook | API key | Logbook stats (QSO count, DXCC total, date range) |\n| `qrz_logbook_fetch` | Logbook | API key | Query QSOs with filters and transparent pagination |\n| `qrz_download` | Logbook | API key | Download full logbook as ADIF |\n| `get_version_info` | — | None | Service version + upstream QRZ API version (fleet identity attestation) |\n\n## Quick Start\n\n### 1. Set up credentials\n\nqrz-mcp uses qso-graph-auth personas for credential management. QRZ has **two separate auth mechanisms** — set up whichever you need:\n\n```bash\n# Install qso-graph-auth if you haven't\npip install qso-graph-auth\n\n# Create a persona\nqso-auth persona create ki7mt --callsign KI7MT\n\n# Enable QRZ provider\nqso-auth persona provider ki7mt qrz --username KI7MT\n\n# Set password (for XML API: qrz_lookup, qrz_dxcc)\nqso-auth persona secret ki7mt qrz\n\n# Set API key (for Logbook API: qrz_logbook_status, qrz_logbook_fetch)\nqso-auth creds set --persona ki7mt --provider qrz --api-key YOUR_API_KEY\n```\n\n**XML API** (callsign lookup, DXCC) requires a QRZ XML Subscription ($35.95/yr). Free tier returns name and address only.\n\n**Logbook API** requires an API key from QRZ Settings > API.\n\n### 2. Configure your MCP client\n\nqrz-mcp works with any MCP-compatible client. Add the server config and restart — tools appear automatically.\n\n#### Claude Desktop\n\nAdd to `claude_desktop_config.json` (`~/Library/Application Support/Claude/` on macOS, `%APPDATA%\\Claude\\` on Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"qrz\": {\n      \"command\": \"qrz-mcp\"\n    }\n  }\n}\n```\n\n#### Claude Code\n\nAdd to `.claude/settings.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"qrz\": {\n      \"command\": \"qrz-mcp\"\n    }\n  }\n}\n```\n\n#### ChatGPT Desktop\n\nChatGPT supports MCP via the [OpenAI Agents SDK](https://developers.openai.com/api/docs/mcp/). Add under Settings > Apps & Connectors, or configure in your agent definition:\n\n```json\n{\n  \"mcpServers\": {\n    \"qrz\": {\n      \"command\": \"qrz-mcp\"\n    }\n  }\n}\n```\n\n#### Cursor\n\nAdd to `.cursor/mcp.json` (project-level) or `~/.cursor/mcp.json` (global):\n\n```json\n{\n  \"mcpServers\": {\n    \"qrz\": {\n      \"command\": \"qrz-mcp\"\n    }\n  }\n}\n```\n\n#### VS Code / GitHub Copilot\n\nAdd to `.vscode/mcp.json` in your workspace:\n\n```json\n{\n  \"servers\": {\n    \"qrz\": {\n      \"command\": \"qrz-mcp\"\n    }\n  }\n}\n```\n\n#### Gemini CLI\n\nAdd to `~/.gemini/settings.json` (global) or `.gemini/settings.json` (project):\n\n```json\n{\n  \"mcpServers\": {\n    \"qrz\": {\n      \"command\": \"qrz-mcp\"\n    }\n  }\n}\n```\n\n### 3. Ask questions\n\n> \"Look up W1AW on QRZ — what's their grid and license class?\"\n\n> \"What DXCC entity is VP8PJ?\"\n\n> \"How many QSOs do I have in my QRZ logbook?\"\n\n> \"Show me all 20m FT8 QSOs from my QRZ logbook this year\"\n\n## Rate Limiting\n\nQRZ enforces undocumented rate limits that can trigger **24-hour IP bans**. qrz-mcp protects you:\n\n- 500ms minimum delay between all API calls\n- Token bucket: 35 requests/minute\n- 60s freeze on authentication failures\n- 3600s freeze on connection refused (IP ban detection)\n- In-memory response cache (5 min for callsigns, 1 hour for DXCC)\n\n## Testing Without Credentials\n\nSet the mock environment variable to test all 4 tools without QRZ credentials:\n\n```bash\nQRZ_MCP_MOCK=1 qrz-mcp\n```\n\n## MCP Inspector\n\n```bash\nqrz-mcp --transport streamable-http --port 8002\n```\n\nThen open the MCP Inspector at `http://localhost:8002`.\n\n## Development\n\n```bash\ngit clone https://github.com/qso-graph/qrz-mcp.git\ncd qrz-mcp\npip install -e .\n```\n\n## QRZ Subscription Tiers\n\n| Feature | Free | XML Data ($35.95/yr) |\n|---------|------|---------------------|\n| Callsign lookups/day | 100 | Unlimited |\n| Fields returned | Name + address only | All (grid, lat/lon, DXCC, class, QSL, image) |\n| Logbook API | No | Yes |\n| DXCC lookup | No | Yes |\n\n## License\n\nGPL-3.0-or-later\n",
  "bytes": 4482,
  "sha": "67f9c2058c40d66b8f4135a0bae51fb5a556e974bacc07e1603befefde0e9c49",
  "repo_slug": "qso-graph/qrz-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_qso_graph_qrz_mcp_6e7ad713/readme"
}