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.

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.

Variable Required Default Purpose
AOTY_BASE_URL No https://aoty.prigoana.com Unofficial Album of the Year API base URL
AOTY_MIN_INTERVAL_MS No 250 Minimum interval between upstream requests

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

Tool Description
get_server_version Return the installed server version
get_attribution Return upstream API and data-source attribution

Albums

Tool Description
get_album Get album details by authoritative slug, or fuzzy artist and name

Search

Tool Description
search_all Search albums, artists, and labels together
search_albums Search album results
search_artists Search artist results
search_labels Search record-label results

Charts and releases

Tool Description
get_new_releases Get paginated new album releases
get_new_singles Get paginated new single releases
get_upcoming_releases Get paginated upcoming releases
get_popular_albums Get currently popular albums
get_popular_singles Get currently popular singles
get_anticipated_albums Get anticipated upcoming albums
get_under_radar_albums Get under-the-radar albums
get_must_hear_albums Get must-hear albums by optional year or decade

Lists and news

Tool Description
get_critic_lists Get critic best-of lists for an optional year
get_critic_list Get the entries in a critic list by slug
get_music_news Get paginated music-news items by feed type

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/

Project links

Data verified by PyPI on Aug 31, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for obrien-matthew from gravatar.com obrien-matthew

Credits

Author: Matthew O'Brien

GitHub Statistics

Data verified by PyPI on Aug 31, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.14

Tags

mcp aoty model-context-protocol

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mcp_aoty-0.1.0.tar.gz (10.2 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

mcp_aoty-0.1.0-py3-none-any.whl (12.7 kB view details)

Uploaded Python 3

File details

Details for the file mcp_aoty-0.1.0.tar.gz.

File metadata

  • Download URL: mcp_aoty-0.1.0.tar.gz
  • Upload date:
  • Size: 10.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for mcp_aoty-0.1.0.tar.gz
Algorithm Hash digest
SHA256 11060fa8821c7ca42720b140765da9cf9c767efeac3adaaebd9cbf802d76ba03
MD5 df68d1ff4d66054ec38c48090aa29684
BLAKE2b-256 d8d2cbdf661f1f9b8b5ded09710c812acb38af35f0458cc1888e7451dff467eb

See more details on using hashes here.

Provenance

The following attestation bundles were made for mcp_aoty-0.1.0.tar.gz:

Publisher: release.yml on obrien-matthew/mcp-aoty

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mcp_aoty-0.1.0-py3-none-any.whl.

File metadata

  • Download URL: mcp_aoty-0.1.0-py3-none-any.whl
  • Upload date:
  • Size: 12.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for mcp_aoty-0.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 8910521998f50fd27f7dbb6ae1e0bb207f380ca87ba7ab93f9726610c5ee3abf
MD5 f5f2cc5629179734c01a55153c5c251b
BLAKE2b-256 dd7e792f75fc0d0c7d2fa618cf7661d19ca67751ba01a3a0fb318f0975dbfa07

See more details on using hashes here.

Provenance

The following attestation bundles were made for mcp_aoty-0.1.0-py3-none-any.whl:

Publisher: release.yml on obrien-matthew/mcp-aoty

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page