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; [email protected]) 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.