mcp-aoty

MCP server for exploring Album of the Year critic and user scores, reviews, releases, charts, critic lists, and music news.

Attribution

Album data comes from the unofficial Album of the Year API at https://aoty.prigoana.com (https://github.com/edideaur/AOTY-api), which is free to use with attribution. Underlying reviews, scores, and editorial content are the work of Album of the Year (https://www.albumoftheyear.org) and its contributing publications.

• Upstream API: aoty.prigoana.com
• Upstream source: edideaur/AOTY-api
• Data source: Album of the Year

That credit is a condition of use, so it is carried in five places and none of them are optional: this section, NOTICE, the User-Agent sent with every request, the instructions string every MCP client receives at handshake, and the get_attribution tool.

Prerequisites

• Python 3.14+
• uv

Setup

uv sync

Configuration

No API key exists or is needed. The request interval is a deliberate courtesy throttle because the upstream API is a free personal Cloudflare Worker.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "aoty": {
      "command": "uvx",
      "args": ["mcp-aoty"],
      "env": {
        "AOTY_MIN_INTERVAL_MS": "250"
      }
    }
  }
}

Claude Code

claude mcp add aoty -e AOTY_MIN_INTERVAL_MS=250 -- uvx mcp-aoty

Tools

Diagnostics

Albums

Search

Charts and releases

Lists and news

Data source and etiquette

albumoftheyear.org has no official API; this server talks only to the unofficial community API and never requests albumoftheyear.org directly. AOTY's robots.txt disallows AI crawlers (ClaudeBot, anthropic-ai, GPTBot, CCBot, Google-Extended) and /search/*, so those directives bind the upstream Worker rather than this client. The API is a scraper and can break when AOTY changes its HTML; keep request volume low.

Known limitations

• artist plus name lookup is fuzzy: Cassius plus 1999 returns the single instead of the LP. Use search_albums, then pass its slug to get_album.
• Album blocks carry no id, so this server derives slugs from their URLs.
• A critic_score_raw value of "NR" means not rated. critic_score is None in that case, which is distinct from a score being absent entirely.
• Search hits often omit scores even when the album page has them. Call get_album with the slug when you need scores.
• A missing album is served as HTTP 200 carrying AOTY's generic page, not a 404. This server detects that stub and raises rather than returning a phantom record titled "Album of the Year".
• Scraped text arrives with HTML entities intact; this server decodes them before returning.
• Scores are live and move.

Development

uv sync
uv run pytest tests/ -x -q
uv run ruff check src/ tests/
uv run pyright src/