# WikiSync/Hiscores MCP for OSRS

A small personal MCP server that exposes data about an Old School RuneScape account
to Claude on demand, to eliminate copy/pasting a bunch if you use Claude to draft a plan
or aggregate wiki data. TBH I am now required to use Claude at work so I'm working on
getting comfortable with it.

- **All of WikiSync -** quests, achievement diaries, skill levels, combat
  achievements, music tracks, league tasks, collection log.
- **Official HiScores -** exact level/xp per skill

Obvious shoutout to the OSRS wiki team and all they do. Ideally I
will eventually turn this into a public API, maybe even add it to the wiki.

## Demo

<img width="1512" height="949" alt="Screenshot 2026-06-14 at 2 30 23 PM" src="https://github.com/user-attachments/assets/e30c8802-a86b-4358-8884-30f6ae264fc2" />

## Tools

| Tool | Description |
| --- | --- |
| `wikisync(username, section="all", profile="STANDARD")` | Sliced WikiSync data. `section` ∈ `quests \| achievement_diaries \| combat_achievements \| collection_log \| music_tracks \| levels \| league_tasks \| all`. `profile` ∈ `STANDARD \| IRONMAN \| HARDCORE_IRONMAN \| ULTIMATE_IRONMAN`. |
| `player_skills(username)` | Exact `{rank, level, xp}` per skill from the official HiScores — the source of truth for XP. |

### Notes & caveats

- **You have to have WikiSync enabled for this to work fully**
- **`collection_log` is empty until manually synced** — the player must press
  the WikiSync button in the in-game collection log interface (and re-press to
  resync). The tool surfaces this as a note rather than a bare `[]`.
- **Quest states** are decoded: `0` not started, `1` in progress, `2` finished
  (confirmed from a live payload).
- `combat_achievements` and `collection_log` return numeric ids (not yet
  decoded to names); quests and diaries are already named.

## Requirements

- Python 3.10+
- [`uv`](https://docs.astral.sh/uv/)

## Setup with Claude Desktop

Claude Desktop launches MCP servers with a stripped-down environment (no shell
`PATH`), so use the **absolute path** to `uv`. Find it with `which uv`.

Edit `claude_desktop_config.json` (Claude Desktop → Settings → Developer → Edit
Config, or `~/Library/Application Support/Claude/` on macOS) and add:

```json
{
  "mcpServers": {
    "osrs-player": {
      "command": "/ABS/PATH/TO/uv",
      "args": [
        "run",
        "--directory", "/ABS/PATH/TO/osrs-wikisync-mcp",
        "osrs-wikisync-mcp"
      ]
    }
  }
}
```

Then **fully quit** Claude Desktop and reopen. The server appears under the tools/MCP 
menu in a chat, and under Settings → Developer. Logs (macos): `~/Library/Logs/Claude/mcp-server-osrs-player.log`.

The MCP server stays alive as long as Claude Desktop is open.

## Manual setup/run

```bash
uv sync
```

```bash
uv run osrs-wikisync-mcp        # stdio (default MCP transport)
# or: uv run python -m osrs_mcp.server
```

## Register with Claude Desktop (recommended)
Claude Code can just call a script so honestly no point in using this
unless you plan to use Claude Desktop. Eventually I'll deploy this
so people can use it on claude.ai and mobile too

```bash
# user scope (available in every session); use an absolute path to this repo
claude mcp add --scope user --transport stdio osrs-player \
  -- uv run --directory /ABS/PATH/TO/osrs-wikisync-mcp osrs-wikisync-mcp

claude mcp list   # then /mcp inside a session to see the tools
```

To iterate on tool I/O and schemas:

```bash
uv run fastmcp dev osrs_mcp/server.py
```

## Data sources

- **HiScores API:** `https://secure.runescape.com/m=hiscore_oldschool/index_lite.ws?player={username}`
- **WikiSync API:** `https://sync.runescape.wiki/runelite/player/{username}/{profile}`

Both are called with a descriptive, contactable `User-Agent` per API etiquette.