Teamfight Tactics Match Analyzer MCP Server

Overview

Teamfight Tactics Match Analyzer MCP Server provides a structured, machine-readable context layer for Teamfight Tactics (TFT) match data so tools and models can reason about games more effectively. It collects match history and match details, enriches events (units, items, outcomes, timestamps), and exposes them through an MCP-compatible API that returns contextual blocks tailored for downstream consumption (LLMs, analytics services, and game assistants).

This server is useful when you need consistent, high-fidelity game context for tasks like automated post-match analysis, coach assistants, replay summaries, or model-driven insights. Instead of fetching raw match payloads and writing bespoke parsers each time, the MCP server centralizes parsing, normalization, caching, and privacy-aware filtering so clients can request ready-to-consume context blocks.

Features

• Normalizes raw TFT match and participant data into consistent context blocks
• Exposes an MCP-compliant HTTP API for requesting match context
• Fetches match history and details from Riot’s match APIs (configurable)
• Caching and rate-limit controls to reduce external API usage
• Configurable enrichment: aggregate stats, top performers, unit/item timelines
• Support for asynchronous job processing (background fetch + enrich)
• Optional Docker deployment for reproducible environments
• Simple configuration via environment variables or configuration file

Installation / Configuration

Minimum prerequisites:

• Git
• A recent Node.js or Python runtime (project uses either—check repository for the exact runtime)
• Riot API key (for match data access)
• Optional: Docker / Docker Compose

Quick start (Git + npm example):

# Clone the repo
git clone https://github.com/GeLi2001/tft-mcp-server.git
cd tft-mcp-server

# Install dependencies (Node.js example)
npm install

# Configure environment variables (see table below)
export RIOT_API_KEY="your-riot-api-key"
export PORT=8080
export CACHE_TTL=3600

# Start the server
npm start

Docker example:

# Build the image
docker build -t tft-mcp-server .

# Run the container (pass env vars)
docker run -e RIOT_API_KEY=your-riot-api-key -p 8080:8080 tft-mcp-server

Example Docker Compose snippet:

version: "3.8"
services:
  tft-mcp:
    image: your-registry/tft-mcp-server:latest
    ports:
      - "8080:8080"
    environment:
      - RIOT_API_KEY=${RIOT_API_KEY}
      - PORT=8080
      - DB_URL=${DB_URL}

Environment variables (common):

Refer to the project’s repo README for exact variable names and additional advanced options.

Available Resources

• GitHub repository: https://github.com/GeLi2001/tft-mcp-server
• API base (typical): http://localhost:8080
• Example endpoints (common patterns — verify in repo API docs):
  • GET /matches?puuid={puuid}&limit={n} — list match IDs for a player
  • GET /match/{matchId} — raw match details
  • GET /mcp/context?matchId={matchId} — MCP-style contextual blocks for a match
  • POST /jobs/fetch — request async fetch/enrich for a match
• Postman / OpenAPI: check the repo for a provided spec or collection

Use Cases

• LLM-driven match summaries

  • Request /mcp/context?matchId=XYZ to get normalized event blocks, then feed them to a language model to generate a concise post-match summary highlighting item builds, stage transitions, and pivotal rounds.

• Automated coaching assistant

  • Periodically fetch a player’s recent matches, aggregate recurring weaknesses (e.g., consistent low early econ), and produce suggestions (build orders, item priorities) using the enriched context.

• Analytics dashboard backend

  • Use the server’s normalized outputs to power charts for unit win rates, item performance per patch, or time-series of player rank changes without re-implementing parsing logic.

• Replay annotation and highlight generation

  • Fetch enriched event timelines and annotate key frames for generating short highlight reels or for training a model to detect clutch plays.

• Rate-limited data pipelines

  • Use caching and background job endpoints to stay within Riot API limits while ensuring downstream systems receive prepared match contexts.

Tips for Developers

• Start by inspecting the available endpoints in the repo’s API docs; the MCP endpoint is usually the one returning context-structured JSON for models.
• Use the CACHE_TTL and DB_URL settings to enable local caching if you expect repeated queries for the same matches.
• When integrating with an LLM, request only the blocks required for the task to stay within input size limits (e.g., summary vs. full timeline).
• Consider running the server behind a reverse proxy and enabling TLS for production deployments.

For full API reference, configuration details, and contribution guidelines, see the project’s GitHub repository: https://github.com/GeLi2001/tft-mcp-server.