RetroAchievements MCP Server
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| MCP_HOST | No | HTTP bind host. Also --host. | 127.0.0.1 |
| MCP_PORT | No | HTTP bind port. Also --port. | 8080 |
| LOG_LEVEL | No | Log level. Logs always go to stderr. | info |
| RA_API_KEY | No | Required. Web API key from your RetroAchievements control panel. RETROACHIEVEMENTS_API_KEY is accepted as an alias. | |
| RA_USERNAME | No | Default user for user-scoped tools. | |
| RA_CACHE_DIR | No | Game-catalog cache directory. 'none' = memory only. | $XDG_CACHE_HOME/retroachievements-mcp |
| MCP_TRANSPORT | No | Transport mode. Default is stdio (http in the container). Or pass --stdio / --http. | stdio |
| RA_RATE_BURST | No | Client-side request burst. | 10 |
| RA_TIMEOUT_MS | No | Upstream request timeout in milliseconds. | 20000 |
| MCP_AUTH_TOKEN | No | Optional bearer token (≥16 chars) required on /mcp. | |
| MCP_ALLOWED_HOSTS | No | Host allowlist for /mcp. Required off-loopback; on loopback defaults to localhost names. '*' disables. | |
| RA_CACHE_MAX_BYTES | No | Response cache byte cap (bodies > 1 MB are never cached). | 64MB |
| RA_CACHE_TTL_SCALE | No | TTL multiplier. 0 disables. | 1 |
| RA_MAX_CONCURRENCY | No | Concurrent upstream requests. | 4 |
| RA_PREWARM_CATALOG | No | Load every console catalog in the background at startup. | false |
| RA_RATE_PER_MINUTE | No | Client-side request pacing per minute. | 72 |
| RA_CACHE_MAX_ENTRIES | No | Response cache max entries. | 500 |
| RETROACHIEVEMENTS_API_KEY | No | Alias for RA_API_KEY. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| get_user_profileC | User profile and points. include: summary (rank, status, recent games/unlocks), awards. |
| get_user_unlocksC | User's unlocks, newest first. One of minutes, from[/to], date; default last 24h. |
| get_user_gamesB | User's game lists: recent, progress (per-game counts + award), completed (100%), want_to_play. |
| get_user_game_progressB | User's progress in one game (summary + achievements with rarity %), or one summary row per game_ids entry. |
| get_user_socialB | User's set requests or dev claims; or who the API-key owner follows / is followed by (ignores user). |
| list_consolesC | IDs of the active RetroAchievements game systems. |
| find_gamesB | Find game IDs by title and/or console. First all-console search may be slow. |
| get_gameC | Game details; include adds achievements (rarity, type), hashes, progression (median times), distribution, claims. |
| get_game_rankingsB | A game's top 10: highest scorers, or most recent masters. |
| get_leaderboardsB | A game's leaderboards (user_entries: the user's entries), or one leaderboard's ranked entries. Give game_id or leaderboard_id. |
| get_achievement_unlocksC | Who unlocked an achievement (newest first), with unlock rates. |
| get_feedC | Site feeds: aotw (Achievement of the Week), top_users, recent_awards, active_claims, claims (finished). |
| get_commentsC | Comment wall of a game, achievement or user (system log entries hidden unless include_system). |
| get_ticketsB | Achievement bug tickets: recent, one ticket, per game/achievement/developer summary, or most_ticketed games. |
| ra_api_rawA | Escape hatch: raw JSON from any RA Web API endpoint (e.g. GetGameExtended). Prefer the dedicated tools. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 15 tools
Most tools target distinct resources (games, users, leaderboards, feeds, tickets), and the parenthetical 'include' hints clarify scope. However, get_user_unlocks vs get_achievement_unlocks and get_user_games vs get_user_game_progress share enough surface that an agent could occasionally misselect, and get_user_profile overlaps those aggregates.
The set follows a strong get_/list_/find_ + noun pattern (get_user_profile, get_game_rankings, list_consoles, find_games), with verb choices reflecting retrieval vs collection vs search semantics. ra_api_raw is the only outlier but is clearly framed as a deliberate escape hatch.
15 tools sits at the top of the well-scoped range and matches a genuinely broad domain (users, games, achievements, leaderboards, tickets, feeds, comments). Each tool maps to a distinct RetroAchievements entity, so none feels redundant.
The surface covers consoles, profiles, unlocks, progress, social, game search/details, rankings, leaderboards, feeds, comments, and tickets, which is close to full lifecycle for a read-only API client. Minor gaps like a dedicated achievement-detail tool are mitigated by get_game's achievement inclusion and the ra_api_raw escape hatch.