retroachievements-mcp

A Model Context Protocol server that exposes the RetroAchievements public API to MCP-compatible clients like Claude Code, Claude Desktop, and Cursor.

Built on top of the official @retroachievements/api TypeScript SDK.

What you can do with it

• "What achievements did I unlock in the last hour?"

• "Summarize my RetroAchievements activity this month."

• "Show me the achievement list for Super Mario 64."

• "Who are the top-ten ranked players right now?"

• "How rare is each achievement in The Legend of Zelda: A Link to the Past?"

Related MCP server: MCP Chess Server

Requirements

• Node.js 18+

• A RetroAchievements account and Web API key (Settings → Keys)

Install

git clone https://github.com/Zach-Houston/retroachievements-mcp.git
cd retroachievements-mcp
npm install
npm run build

First-time setup

You have three ways to get the server credentials in place. Pick whichever fits.

1. In-chat (the magic path)

Just start asking your MCP client questions like "Show me my RetroAchievements profile." The first call will fail with a structured "credentials not configured" message that prompts the assistant to ask you for your Web API key. Paste it, and the assistant calls ra_save_credentials, which validates the key against the live API and writes it to your user config dir (%APPDATA%\retroachievements-mcp\credentials.json on Windows, ~/Library/Application Support/retroachievements-mcp/ on macOS, $XDG_CONFIG_HOME/retroachievements-mcp/ on Linux). All future tool calls just work.

The assistant can also call ra_status at any time to check whether setup is needed.

Note: pasting an API key into chat means it ends up in conversation history. If you'd rather keep it out of the transcript, use option 2 or 3 below.

2. Interactive CLI

npm run setup

Walks you through getting an account (if needed), prompts for your Web API key, verifies against the API, and saves to the same user config dir.

3. Env vars in your MCP client config

Set RA_USERNAME and RA_API_KEY as env entries in your MCP client's server config (see Use with Claude Code). The server reads env vars first, then falls back to the stored file. Env vars never touch the chat history.

Configure

The server reads two environment variables at startup:

A .env.example is included as a template — copy it to .env for local dev, or pass the values as env entries in your MCP client config (see below).

If you launch the server without these set, it will still start and respond to MCP clients — but every tool call returns a friendly error explaining how to finish setup. This means a missing key never silently bricks the connection.

Use with Claude Code

Add this to your Claude Code MCP config (~/.claude.json or via claude mcp add):

{
  "mcpServers": {
    "retroachievements": {
      "command": "node",
      "args": ["C:/Users/Z/projects/retroachievements-mcp/dist/index.js"],
      "env": {
        "RA_USERNAME": "YourUserName",
        "RA_API_KEY": "your-web-api-key"
      }
    }
  }
}

Or, after npm link, you can use the retroachievements-mcp binary directly.

Use with Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "retroachievements": {
      "command": "node",
      "args": ["C:/Users/Z/projects/retroachievements-mcp/dist/index.js"],
      "env": {
        "RA_USERNAME": "YourUserName",
        "RA_API_KEY": "your-web-api-key"
      }
    }
  }
}

Tools

Setup

User

Game

Feed

More tools (leaderboards, console game lists, comments, tickets, claims, hashes, distribution) are planned — see src/tools/ to add your own.

Develop

npm run dev     # tsx, no build step
npm run build   # compile to dist/
npm start       # run the compiled server

License

MIT