OSRS MCP Server

MCP server for the Old School RuneScape Wiki, in-game data definitions, Grand Exchange prices, and hiscores. Live data from oldschool.runescape.wiki with proper redirect handling, retry/backoff, identifying User-Agent, and section + wikitext + extracts tools.

This is a community fork: previous work by @JayArrowz (much appreciated). Forked here to add better pagination, redirect handling, identifying User-Agent, additional retrieval modes (wikitext / extracts / section / opensearch), and polite client behavior.

Tools

OSRS Wiki

#	Tool	Description
1	osrs_wiki_search	Full-text search of the OSRS Wiki (CirrusSearch). Returns snippets with section titles.
2	osrs_wiki_get_page_info	Get metadata (pageid, length, last modified, redirects) for one or more titles.
3	osrs_wiki_parse_page	Full-page parse → rendered HTML. Follows redirects automatically.
4	osrs_wiki_wikitext	New. Raw wikitext for a page (preserves templates/infoboxes). Useful for AI to see templated context.
5	osrs_wiki_extract	New. Cheap plain-text or limited-HTML extract via the search index. Much faster than full parse. Supports intro, chars cap, sectionformat.
6	osrs_wiki_parse_section	New. Parse a single section by 0-based index (saves tokens on huge pages like Slayer).
7	osrs_wiki_opensearch	New. Title autocomplete (e.g., "abys" → Abyssal whip / dagger / demon). Returns tidy {title, description, url} rows.

All wiki tools follow redirects=1, set an identifying User-Agent, and retry on 429/503 with exponential backoff. The client also honors the wiki's maxlag advisory by waiting and retrying once.

Game Data Search (local cache files)

search_varptypes · search_varbittypes · search_iftypes · search_invtypes
search_loctypes · search_npctypes · search_objtypes · search_rowtypes
search_seqtypes · search_soundtypes · search_spottypes · search_spritetypes
search_tabletypes

Plus the generic file tools: search_data_file, get_file_details, list_data_files.

Live OSRS Data

• lookup_player — Hiscores stats (skills, bosses, clues, activities).
• search_ge_items — Search GE items by name (the underlying mapping is cached on first call).
• get_ge_latest / get_ge_timeseries — Instant and historical Grand Exchange prices.

Installation

npx -y mcp-osrs

…or, locally:

git clone https://github.com/fisherrjd/mcp-osrs.git
cd mcp-osrs
npm install
npm run build

Configuration

Add to your MCP client's mcpServers config:

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

Path config for claude_desktop_config.json:

OS	Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%/Claude/claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

Requirements

• Node.js 18+
• Outbound HTTPS access to oldschool.runescape.wiki, prices.runescape.wiki, and secure.runescape.com (hiscores).

Examples

# Search wiki
> search the OSRS Wiki for pages matching "dragon"

# Get an intro summary only — fast and small
> get an intro paragraph for the Abyssal whip page

# Parse just one section of a long page
> parse section 3 of "Slayer"

# Autocomplete a title
> wiki title autocomplete for "abys"

# Get raw wikitext for infobox data
> get the wikitext for "Abyssal_whip"

# Player + GE
> how's Zezima doing?  +  what's the 1h price history of cannonballs (id 2)?

What changed vs upstream

Before (@jayarrowz/mcp-osrs 0.7.x)	This fork (mcp-osrs 0.8.x)
Bare axios/1.x User-Agent — throttled by the wiki	Identifying UA: mcp-osrs/0.8.0 (+https://github.com/fisherrjd/mcp-osrs; +discord:rjfisher; dev@jade.rip) node/<v>
No retry / backoff	3 retries on 429/5xx with exponential backoff; honors Retry-After
No maxlag handling	Honors wiki's maxlag advisory (one retry with jittered delay)
parse_page did not follow redirects ("Abyssal whip" → "Abyssal_whip" fails)	parse_page, wikitext, extract, parse_section all set redirects=1
Only rendered HTML output (prop=text)	+ raw wikitext, cheap extracts, per-section, opensearch autocomplete
Timeout: none	10 s per request
gzip, etc. headers not set	Accept-Encoding: gzip, deflate
Source code refs jayarrowz everywhere	Renamed to fisherrjd (GitHub username); author rjfisher is their Discord handle; bare mcp-osrs on npm; all data path clients ship the same UA

Bonus: upstream pi-web-access patch

This fork ships a minimal patch for a known crash in the upstream pi package: @nicobailon/pi-web-access v0.13.0 has a ReferenceError: sendCuratorFallbackUpdate is not defined bug — issue #103 — that kills pi when the search curator can't open a browser. The fix (hoist a let binding out of the try block so the catch can see it) is captured in patches/pi-web-access+0.13.0.patch. Apply with patch -p0 -i patches/pi-web-access+0.13.0.patch (after the file has been checked out from v0.13.0).

Development

npm install
npm run build   # tsc + chmod + copy data
npm test        # jest unit tests
npm start       # stdio MCP server

License

MIT — see LICENSE. Upstream: JayArrowz/mcp-osrs.