RetroAchievements MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@RetroAchievements MCP Server how am I doing on Chrono Trigger?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
retroachievements-mcp
A token-efficient Model Context Protocol server for the
RetroAchievements Web API. It covers all 38 documented API_Get*
endpoints through 15 read-only tools, and runs over stdio for local clients or Streamable
HTTP for a hosted endpoint.
Why another one
Raw RetroAchievements responses are large and repetitive. GetClaims returns ~400 KB,
GetAchievementOfTheWeek ~69 KB, and GetGameList repeats a dozen keys on every one of thousands
of rows. Passing that through to a model wastes context. This server shapes every response:
Call | Raw upstream | Tool output |
Achievement of the week | 69,150 B | ~790 chars |
Recent claims (10) | 398,397 B | ~1,150 chars |
Game + all 35 achievements | 15,963 B | ~4,000 chars |
User progress on a game (5 locked achievements + rank) | 34,610 B | ~820 chars |
How it does that:
Compact output. JSON has no whitespace. Lists come back as tables (
{"cols":[…],"rows":[[…]]}). Empty fields and all-empty columns are dropped. Timestamps are shortened, and images are omitted unless you ask for them.Projection. Each tool returns the fields a model actually uses, under short names. Duplicate and internal fields (
MemAddr, ULIDs, forum IDs, rich-presence scripts) are dropped.Server-side filtering and pagination. Examples: locked achievements only, games by award status, the newest N unlocks. Results carry
total/next_offsetonly when truncated.Few tools. 15 tools cover all 38 endpoints, which keeps the per-turn tool-schema cost low.
API efficiency. Every upstream call goes through:
a per-endpoint TTL cache;
request coalescing for identical in-flight calls;
a concurrency ceiling and a client-side rate limiter tuned to RetroAchievements' observed limits, with retries and backoff on 429/5xx.
Game search. RetroAchievements has no search endpoint, so per-console game catalogs are cached on disk.
find_gamessearches every system without re-downloading 80+ catalogs on each run.
Related MCP server: redmine-mcp
Tools
Tool | Covers |
| profile, summary (rank, status, recent games/unlocks), site awards |
| achievements unlocked in the last N minutes, a date range, or on a day |
| recently played, completion progress (filter by mastered/beaten/…), completed, want-to-play |
| one game's progress + locked/unlocked achievements with rarity; or a multi-game summary |
| following, followers, set requests, claims |
| search titles across all consoles, or list a console's games |
| console/system IDs |
| game info, plus achievements, hashes, progression/median times, unlock distribution, claims |
| high scores / latest masters |
| a game's leaderboards, a leaderboard's entries, or a user's entries on a game |
| who unlocked an achievement, with rarity |
| achievement of the week, top users, recent game awards, active/completed/dropped/expired claims |
| comments on a game, achievement, or user wall |
| tickets: recent, by id, by game/achievement/developer, most-ticketed games |
| escape hatch: any endpoint, cleaned and size-capped |
All user-scoped tools default to RA_USERNAME, so "how am I doing on Chrono Trigger?" needs no
username argument.
Configuration
Get a Web API key from your RetroAchievements control panel.
Env | Default | |
| — | Required. |
| — | Default user for user-scoped tools. |
|
| Or pass |
|
| HTTP bind. Also |
| — | Host allowlist for |
| — | Optional bearer token (≥16 chars) required on |
|
| Game-catalog cache. |
|
| Load every console catalog in the background at startup. |
|
| Client-side request pacing; a 429 pauses all requests. |
|
| Concurrent upstream requests. |
|
| Response cache byte cap (bodies > 1 MB are never cached). |
|
| Response cache size; TTL multiplier ( |
|
| Upstream request timeout. |
|
| Logs always go to stderr. |
Running locally (stdio)
Claude Code, from a release tarball (fast: prebuilt, runtime dependencies only):
claude mcp add retroachievements \
-e RA_API_KEY=your-key -e RA_USERNAME=your-name \
-- npx -y https://github.com/sharkusmanch/retroachievements-mcp/releases/download/v0.1.0/sharkusmanch-retroachievements-mcp-0.1.0.tgzOr straight from git. This builds on first launch (~1 minute with dev dependencies), so start it once
in a terminal before a client with a short startup timeout uses it:
npx -y github:sharkusmanch/retroachievements-mcp --version.
Any MCP client (mcpServers JSON):
{
"mcpServers": {
"retroachievements": {
"command": "npx",
"args": [
"-y",
"https://github.com/sharkusmanch/retroachievements-mcp/releases/download/v0.1.0/sharkusmanch-retroachievements-mcp-0.1.0.tgz"
],
"env": { "RA_API_KEY": "your-key", "RA_USERNAME": "your-name" }
}
}
}Or run the container over stdio. The named volume keeps the game-catalog cache between sessions:
{
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"RA_API_KEY",
"-e",
"RA_USERNAME",
"-v",
"retroachievements-mcp-cache:/tmp/retroachievements-mcp",
"ghcr.io/sharkusmanch/retroachievements-mcp:latest",
"--stdio"
],
"env": { "RA_API_KEY": "your-key", "RA_USERNAME": "your-name" }
}Every GitHub release attaches the tarball (sharkusmanch-retroachievements-mcp-X.Y.Z.tgz) with a provenance attestation.
Running as a service (Streamable HTTP)
docker run -d -p 8080:8080 \
-e RA_API_KEY=your-key -e RA_USERNAME=your-name \
-e MCP_ALLOWED_HOSTS=ra-mcp.example.com \
-e MCP_AUTH_TOKEN=a-long-random-token \
ghcr.io/sharkusmanch/retroachievements-mcp:latestPOST /mcp: stateless Streamable HTTP.GET/DELETEreturn 405.GET /healthz: liveness. It is outside the host/auth guards, and it never checks upstream health.
claude mcp add --transport http retroachievements https://ra-mcp.example.com/mcp \
--header "Authorization: Bearer a-long-random-token"The container runs as uid 1000 and works with a read-only root filesystem when /tmp is writable
(the catalog cache defaults to /tmp/retroachievements-mcp in the image).
Supply chain
Releases are cut from v* tags only. Each release publishes:
a multi-arch image (
linux/amd64,linux/arm64) to GHCR, with a SLSA build-provenance attestation and an SPDX SBOM attestation stored in the registry;an npm tarball with its own provenance attestation, attached to the GitHub release.
Verify:
gh attestation verify oci://ghcr.io/sharkusmanch/retroachievements-mcp:vX.Y.Z --owner sharkusmanchDevelopment
npm ci
npm run lint && npm run typecheck && npm test
npm run build
RA_API_KEY=… RA_USERNAME=… node scripts/smoke.mjs # tool list + schema sizes
RA_API_KEY=… node scripts/smoke.mjs find_games '{"query":"chrono trigger"}'See DESIGN.md for the design rules.
License
MIT
Available Tools
15 toolsfind_gamesBRead-only
Find game IDs by title and/or console. First all-console search may be slow.
Inputs: limit, query, offset, console_id, +1 more.
get_achievement_unlocksCRead-only
Who unlocked an achievement (newest first), with unlock rates.
Inputs: achievement_id (required), limit, offset, hardcore_only.
get_commentsCRead-only
Comment wall of a game, achievement or user (system log entries hidden unless include_system).
Inputs: target (required), id, sort, limit, +2 more.
get_feedCRead-only
Site feeds: aotw (Achievement of the Week), top_users, recent_awards, active_claims, claims (finished).
Inputs: kind (required), date, limit, offset, +4 more.
get_gameCRead-only
Game details; include adds achievements (rarity, type), hashes, progression (median times), distribution, claims.
Inputs: game_id (required), limit, images, offset, +2 more.
get_game_rankingsBRead-only
A game's top 10: highest scorers, or most recent masters.
Inputs: game_id (required), type.
get_leaderboardsBRead-only
A game's leaderboards (user_entries: the user's entries), or one leaderboard's ranked entries. Give game_id or leaderboard_id.
Inputs: user, limit, offset, game_id, +2 more.
get_ticketsBRead-only
Achievement bug tickets: recent, one ticket, per game/achievement/developer summary, or most_ticketed games.
Inputs: mode (required), id, user, limit, +3 more.
get_user_game_progressBRead-only
User's progress in one game (summary + achievements with rarity %), or one summary row per game_ids entry.
Inputs: sort, user, limit, images, +5 more.
get_user_gamesBRead-only
User's game lists: recent, progress (per-game counts + award), completed (100%), want_to_play.
Inputs: list (required), sort, user, limit, +4 more.
get_user_profileCRead-only
User profile and points. include: summary (rank, status, recent games/unlocks), awards.
Inputs: user, limit, images, include.
get_user_socialBRead-only
User's set requests or dev claims; or who the API-key owner follows / is followed by (ignores user).
Inputs: kind (required), user, limit, offset, +1 more.
get_user_unlocksCRead-only
User's unlocks, newest first. One of minutes, from[/to], date; default last 24h.
Inputs: to, date, from, user, +3 more.
list_consolesCRead-only
IDs of the active RetroAchievements game systems.
Inputs: no named parameters.
ra_api_rawARead-only
Escape hatch: raw JSON from any RA Web API endpoint (e.g. GetGameExtended). Prefer the dedicated tools.
Inputs: endpoint (required), params, max_chars.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
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.
Maintenance
Related MCP Connectors
Search Bluesky posts and feeds; read profiles, threads, and trends. STDIO or Streamable HTTP.
Unofficial, read-only access to your Last.fm listening history, charts, and music lookups.
Four public utilities plus seven OAuth-protected Remote read tools for paired Nymrel devices.
Live X/Twitter data: profiles, tweets, search, followers, lists and trends. 29 read-only tools.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables interaction with the full public ListenBrainz API, exposing 37 tools for listens, stats, playlists, radio, social, and cover art over stdio.371BSD Zero Clause
- FlicenseAqualityBmaintenanceProvides read-only MCP tools over stdio for interacting with a Redmine instance, enabling users to list and retrieve projects, issues, queries, wiki pages, and other Redmine resources via the REST API.35-
- AlicenseAqualityBmaintenanceExposes fourteen read-only tools over the HEY Research public API, letting assistants look up Robinhood Chain projects, builders, shipped work, relationships and market context, with each answer tagged FACT, DERIVED or UNKNOWN and unmeasured fields omitted rather than zeroed. Runs over stdio or hosted Streamable HTTP, and gives no trade instructions.131MIT
- AlicenseNot gradedqualityCmaintenanceGives MCP clients read-only access to every GET endpoint of Apple's Campaign Management v5 and Apple Ads Platform v1 APIs across multiple ad accounts, over stdio or Streamable HTTP. It exposes one tool per endpoint with per-account OAuth handling, pagination, and structured errors, while excluding all mutation and POST-only reporting endpoints.94 npmMIT