mcp-osrs

An MCP server for Old School RuneScape. It answers whole player questions in one call: "can I do Dragon Slayer II?", "what do I bring on each trip?", "how do I get these items as an ironman?", "what's a whip worth?". It combines the OSRS Wiki's structured data, Quest Helper's quest definitions, real-time Grand Exchange prices and the player's own account.

Answers are compact JSON under 12 KB, carry their source URLs and the age of any live data, and continue long lists with a cursor.

Install

Requires Node.js 20 or newer. The server speaks MCP over stdio and is started with npx.

Claude Code

claude mcp add -s user osrs -- npx -y @slest1/mcp-osrs

Claude Desktop, Cursor, Windsurf, Gemini CLI

Add this to the client's MCP configuration file:

{
  "mcpServers": {
    "osrs": {
      "command": "npx",
      "args": ["-y", "@slest1/mcp-osrs"]
    }
  }
}

Client	Configuration file
Claude Desktop	claude_desktop_config.json (Settings → Developer → Edit Config)
Cursor	~/.cursor/mcp.json, or .cursor/mcp.json in a project
Windsurf	~/.codeium/windsurf/mcp_config.json
Gemini CLI	~/.gemini/settings.json

VS Code

In .vscode/mcp.json (or the user-level MCP configuration):

{
  "servers": {
    "osrs": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@slest1/mcp-osrs"]
    }
  }
}

Codex CLI

codex mcp add osrs -- npx -y @slest1/mcp-osrs

or in ~/.codex/config.toml:

[mcp_servers.osrs]
command = "npx"
args = ["-y", "@slest1/mcp-osrs"]

Any other stdio client

Run npx -y @slest1/mcp-osrs as the server command. Settings go in environment variables (see Configuration).

From source

git clone https://github.com/slest1/mcp-osrs.git
cd mcp-osrs
npm ci
npm run build
node dist/index.js --version

Point your client at node /path/to/mcp-osrs/dist/index.js.

Troubleshooting

• npx not found, or the server never starts from a desktop app. Desktop apps often don't inherit your shell's PATH. Use the absolute path to npx (from which npx, or where npx on Windows) as the command.
• Updating. npx caches packages. Use @slest1/mcp-osrs@latest in the arguments to always get the newest release, or clear the npx cache.
• Checking the install. npx -y @slest1/mcp-osrs --version prints the version. Logs go to stderr as JSON lines; set LOG_LEVEL=debug for more.

Tools

Group	Tool	What it answers
Account	set_account	Save the player's name and mode so later answers are checked against it
Account	get_account	Which account is saved and where it came from
Account	lookup_player	Hiscores: levels, XP, ranks, boss kills, clues and combat level
Account	get_player_progress	WikiSync quests, diaries, collection log and combat achievements
Wiki	search_wiki	Search the OSRS Wiki
Wiki	get_page	Read an article or one section as clean text
Wiki	get_page_sections	List an article's sections
Wiki	query_wiki_data	Query any wiki Bucket table directly
GE	get_price	Live prices, margin after GE tax, volumes, buy limits, batch totals
GE	get_price_history	Price history with low, high, average and % change
Items	get_item	Item facts, equipment bonuses, versions and live price
Items	find_item_sources	How to get items or a quest's items, with a practical recommendation for each
Items	get_shop	A shop's stock, prices and restock times
Items	find_recipes	Recipes that make or use an item, or train a skill
Monsters	get_monster	Stats, weaknesses, slayer info and map-linked locations
Monsters	get_drops	Drop table at live prices and expected gp per kill
Quests	get_quest	Can the player start it, prerequisites ✓/✗/?, rewards
Quests	get_quest_guide	Quest Helper's steps, one section at a time
Quests	plan_quest_trips	What to bring on each trip, fitted to 28 slots
Quests	suggest_quests	The next quests in the optimal order the player can start
Achievements	get_diary	Diary requirements, tasks, completion and rewards
Achievements	get_slayer_tasks	A slayer master's tasks, weights and chances
Achievements	get_combat_achievements	Combat achievement tasks, points and completion
Skills	plan_skill	XP to a goal, actions and materials, best methods and XP quests
Skills	get_money_makers	Money-making methods by gp/hr that the account can do
Clues	solve_clue	Solutions for anagrams, ciphers, cryptics and emote clues

Personalization

• Save an account once. Ask the assistant to save your name and mode (set_account). Modes are main, ironman, hardcore_ironman, ultimate_ironman, deadman and seasonal. The account is stored in a small JSON file (see OSRS_STATE_FILE). Without a saved account, answers are generic and the first personal question includes a one-time hint.
• A player argument overrides the saved account for one call.
• Hiscores give skill levels to every tool that checks requirements.
• WikiSync is opt-in: install the WikiSync plugin in RuneLite and log in. It unlocks quest, diary, collection log and combat achievement checks, quest points and finished-quest skipping in suggestions. Without it those checks show ?. Deadman accounts have no WikiSync data.
• Ironman modes get Quest Helper's ironman quest data, the ironman quest order, procurement plans that never use the GE, and ironman notes on quests.

Configuration

Every setting is optional and read from the environment. Invalid values stop the server at startup with a message naming the variable.

Variable	Default	Meaning
OSRS_ACCOUNT	none	Default player name until one is saved with set_account
OSRS_ACCOUNT_MODE	main	Default account mode
OSRS_STATE_FILE	$XDG_CONFIG_HOME/mcp-osrs/state.json, else ~/.config/mcp-osrs/state.json	Saved-account file; off disables saving
OSRS_CACHE_DIR	$XDG_CACHE_HOME/mcp-osrs, else ~/.cache/mcp-osrs	Where the quest data release is cached
OSRS_WIKI_URL	https://oldschool.runescape.wiki/api.php	Wiki API
OSRS_PRICES_URL	https://prices.runescape.wiki/api/v1/osrs	Real-time prices API
OSRS_HISCORES_URL	https://secure.runescape.com	Official hiscores
OSRS_WIKISYNC_URL	https://sync.runescape.wiki	WikiSync
OSRS_DATA_URL	https://github.com/slest1/osrs-data/releases/latest/download	Quest data release
OSRS_MAX_RESPONSE_BYTES	12288	Response size cap
OSRS_CACHE_MAX_ENTRIES	1000	In-memory response cache size
OSRS_MAX_CONCURRENCY	4	Concurrent requests per host
OSRS_REQUEST_TIMEOUT_MS	15000	Timeout per request
LOG_LEVEL	info	debug, info, warn, error or silent (logs go to stderr)

For example, in an mcpServers entry:

"env": { "OSRS_ACCOUNT": "Zezima", "OSRS_ACCOUNT_MODE": "ironman" }

Data sources

Source	Used for	Cached
OSRS Wiki Action API and Bucket tables	Articles, items, monsters, drops, shops, recipes, quests, diaries, clues, money making	1 hour; large catalogs 24 hours
OSRS Wiki real-time prices	Item mapping, latest prices, averages, history	1 minute to 24 hours
Official hiscores	Skills, bosses, clues	5 minutes
WikiSync	Quests, diaries, collection log, combat achievements	5 minutes
osrs-data releases	Quest Helper quest data, verified by sha256	On disk, checked daily; a bundled snapshot is the fallback

Every request sends the User-Agent mcp-osrs/<version> (+https://github.com/slest1/mcp-osrs), respects a per-host concurrency limit, and retries with backoff that honours Retry-After.

Development

npm ci
npm run check        # typecheck, lint and tests
npm run build        # compile to dist/
npm run dev          # run from source with tsx

Script	Does
dev	Run the server from source
build	Compile to dist/
start	Run the compiled server
typecheck	TypeScript, no emit
lint / format	Biome check, or check and fix
test / test:watch	Vitest
check	typecheck, lint and test
fixtures:record	Re-record the HTTP fixtures from the live APIs (optionally only named scenarios)

Tests never touch the network: they replay recorded responses from test/fixtures/<host>/, and the integration tests drive the real server through an MCP client over an in-memory transport. To add or refresh fixtures, add a scenario to test/support/scenarios.ts and run npm run fixtures:record -- <scenario>.

A weekly CI job (the drift canary) re-records every scenario, runs the tests against the fresh recordings, compares src/sources/wiki/tables.ts with the live Bucket schemas (scripts/check-drift.ts) and checks the bundled quest data against the latest osrs-data release.

docs/extending.md has step-by-step recipes for adding tools, data sources, wiki tables and more.

Licence and attribution

• The MIT licence (see LICENSE) covers this project's code only.
• Wiki content, both fetched at runtime and recorded in test/fixtures/, is from the Old School RuneScape Wiki under CC BY-NC-SA 3.0, the licence the wiki declares; answers link the pages they draw on. test/fixtures/NOTICE lists the sources of every recorded response.
• The bundled quest data in data/osrsdata/ comes from Quest Helper by Zoinkwiz and contributors, under the BSD 2-Clause License, via the osrs-data releases; data/osrsdata/NOTICE has the licence text, and it ships in the npm package. Quest answers carry this attribution.
• Prices come from the OSRS Wiki real-time prices API.
• Hiscores are Jagex's public data. Old School RuneScape is a trademark of Jagex Ltd; this project is not affiliated with Jagex.