Riot MCP Server (TypeScript)

This project implements an MCP-compatible Riot Games data server using the @modelcontextprotocol/sdk.

Prerequisites

• Node.js 18+
• A Riot Games Developer API key (RIOT_API_KEY)

Setup

npm install

Create a local .env (or otherwise export the variable) with your Riot key:

export RIOT_API_KEY="your-riot-api-key"

If you prefer using a file, create .env alongside the project with:

RIOT_API_KEY=your-riot-api-key

Running

• Development (TS with live reload):

  npm run dev

• Production build + run:

  npm run build
  npm start

The server listens on stdio, so hook it into an MCP-compatible client (e.g. Claude Desktop, VS Code MCP, MCP Inspector) by configuring the command npm run dev (or the built build output) as the server entrypoint.

Available Tools

| Tool ID | Description | Key Arguments | | --- | --- | --- | | riot.getTopChampions | Lists the champions a player has the highest mastery on. | gameName, tagLine, optional platformRouting (default na1), optional regionalRouting, optional language (default en_US), count (max 10). | | riot.getChampionMastery | Returns mastery stats for a specific champion. | Same region/language args as above plus championName (locale aware). | | riot.getMatchHistory | Retrieves recent matches with win/loss, KDA, vision, CS, and damage statistics. | count (max 10), optional start, optional queue filter, plus standard routing args. | | riot.getMatchSummary | Detailed stats for a single match for the specified player. | matchId, either puuid or gameName+tagLine, plus routing args. | | riot.getPlayerSummary | Aggregates profile info, ranks, top champions, and recent match stats. | matchCount and topChampionCount control list sizes; accepts routing and language overrides. |

Region & Routing

• platformRouting corresponds to the platform shard (e.g. na1, euw1, kr, br1, sg2).
• regionalRouting corresponds to the match/account routing group (americas, europe, asia, sea). If omitted, it is derived from the platform automatically; you can override it when necessary (e.g. TFT or Valorant endpoints).

Localization

Champion names are pulled from Data Dragon using the requested language (default en_US). Invalid locales result in a descriptive error.

Development Notes

• npm run dev uses tsx watch for a fast development loop.
• npm run build outputs compiled files in dist/.
• The code caches champion metadata per language to avoid repeated Data Dragon requests.
• All tool responses include both a readable text summary and structuredContent validated against Zod schemas, making the data easy for clients to consume programmatically.

License

MIT License.