# LoL Data MCP Server

[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
[![MCP over stdio](https://img.shields.io/badge/MCP-stdio-555555)](https://modelcontextprotocol.io/)
[![Selenium](https://img.shields.io/badge/Selenium-43B02A?logo=selenium&logoColor=white)](https://www.selenium.dev/)
[![MIT licence](https://img.shields.io/github/license/Estaed/Lol_Data_MCP_Server)](LICENSE)

**An MCP server that lets an AI assistant look up League of Legends champions, items and runes on the official LoL Wiki.**

You ask the assistant in your editor: "What are Taric's stats at level 6?"
The assistant calls this server's `get_champion_stats` tool with `{"champion": "Taric", "level": 6}`.
The server opens Taric's wiki page in a headless browser, picks level 6 in the stats dropdown, and returns the numbers as JSON.

- **What it does:** 9 MCP tools. They return champion stats (any level 1 to 18), abilities, item data, rune data, and patch history for champions, items and runes.
- **Why you can trust the numbers:** every answer is read from [wiki.leagueoflegends.com](https://wiki.leagueoflegends.com/en-us/) when you ask, so it follows the wiki's current patch.
- **Who decides:** the assistant picks the tool and the arguments; the server only reads and structures the wiki page.

Personal project, 2025. Part of **Project Taric**, four repos with one goal, an AI that plays Taric:

| Repo | Part | What exists |
|---|---|---|
| [Taric_Bot_Data](https://github.com/Estaed/Taric_Bot_Data) | The author's own Taric games | Riot API collection and feature scripts |
| **Lol_Data_MCP_Server** (this repo) | Game data for the other parts | A working MCP server with 9 tools |
| [Lol_Sim_Env](https://github.com/Estaed/Lol_Sim_Env) | The training lane for RL | Core game classes |
| [Taric_AI_Agent](https://github.com/Estaed/Taric_AI_Agent) | The agent (IL + RL) | Design documents |

## Quick start

You need Python 3.9 or newer and Google Chrome (Selenium drives it headless for stats, abilities and patch notes).

```bash
git clone https://github.com/Estaed/Lol_Data_MCP_Server.git
cd Lol_Data_MCP_Server
python -m venv venv
venv\Scripts\activate            # Windows; on macOS/Linux: source venv/bin/activate
pip install -r requirements.txt
python -m src.mcp_server.stdio_server
```

The server reads one JSON-RPC message per line on stdin and answers on stdout. To check it by hand, paste this line; it answers with the 9 tools:

```json
{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}
```

A tool call from the editor looks like this (sent as one line):

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {"name": "get_champion_stats", "arguments": {"champion": "Taric", "level": 6}}
}
```

To use it from Cursor, add it to the MCP settings. This follows the repo's own Windows setup; put your folder in place of `<path>`:

```json
{
  "mcpServers": {
    "lol-data": {
      "command": "powershell",
      "args": [
        "-Command",
        "cd '<path>\\Lol_Data_MCP_Server'; .\\venv\\Scripts\\python -m src.mcp_server.stdio_server"
      ]
    }
  }
}
```

## How it works

```mermaid
flowchart LR
    A["AI assistant<br/>(Cursor)"] --> B["stdio server<br/>JSON-RPC lines"]
    B --> C["MCPHandler<br/>9 tools"]
    C --> D["Services<br/>champions, items, runes"]
    D --> E["Scrapers<br/>httpx, BeautifulSoup, Selenium"]
    E --> F["LoL Wiki"]
    classDef lit stroke:#C23C00,stroke-width:3px
    class E lit
```

1. **Connect.** `stdio_server.py` reads one JSON message per line. `MCPHandler` answers `initialize`, `tools/list` and `tools/call`.
2. **Pick a tool.** A `ToolRegistry` holds the 9 tools. Each tool publishes a JSON schema for its arguments in `tools/list`.
3. **Ask a service.** Each tool calls a service for champions, items or runes (`src/services/`).
4. **Scrape the wiki.** The scrapers fetch pages with `httpx` and parse them with BeautifulSoup. Champion pages that need clicks (the level dropdown, ability details, patch history) run in headless Chrome through Selenium. Page requests wait at least 1 s apart, and champion pages are cached on disk for 24 hours.
5. **Answer.** The result goes back as JSON text inside the MCP response.

<details>
<summary>The 9 tools and their arguments</summary>

| Tool | Required | Optional | Returns |
|---|---|---|---|
| `get_champion_stats` | `champion` | `level` (1 to 18) | Base stats, or stats at that level |
| `get_champion_abilities` | `champion` | `ability_slot` (Q, W, E, R, Passive) | All abilities, or one |
| `get_champion_patch_note` | `champion_name` | `patch_version` | Patch history, or one patch |
| `get_item_data` | `item_name` | `sections` | Stats, recipe, cost analysis, notes, similar items |
| `get_item_patch_note` | `item_name` | `patch_version` | Item patch history |
| `get_rune_data` | `rune_name` | `sections` | Sidebar, notes and strategy |
| `get_rune_patch_note` | `rune_name` | `patch_version` | Rune patch history |
| `ping` | | `message` | Echo, to test the connection |
| `server_info` | | | Name, version and tool count |

</details>

<details>
<summary>HTTP server, tests and project files</summary>

**HTTP and WebSocket.** `src/mcp_server/server.py` runs the same handler in FastAPI, for testing without an editor. It listens on `localhost:8000`, with `GET /health` and a WebSocket at `/mcp`:

```bash
python -m src.mcp_server.server
```

**Tests.** Tests for champion stats and abilities, items and runes are in `tests/`. Run them from the repo root:

```bash
pytest
```

**Configuration.** YAML files in `config/` hold server, data-source and per-environment settings.

**Documents.**

- [`docs/lol_data_mcp_server.md`](docs/lol_data_mcp_server.md): the full specification and task log.
- [`docs/RECOMMENDATIONS.md`](docs/RECOMMENDATIONS.md): performance recommendations, ordered by file.
- [`src/mcp_server/README.md`](src/mcp_server/README.md): what each server file does.

**Role in Project Taric.** The server is the data source for the other parts: champion, item and rune data for the simulator ([Lol_Sim_Env](https://github.com/Estaed/Lol_Sim_Env)) and the agent ([Taric_AI_Agent](https://github.com/Estaed/Taric_AI_Agent)).

</details>

---

LoL Data MCP Server is not endorsed by Riot Games. League of Legends is a trademark of Riot Games, Inc.