osrs-mcp

MCP server for Old School RuneScape. Gives an AI agent eyes and knowledge for OSRS by combining:

• Screen vision — captures the RuneLite window and uses Claude or a local vision LLM to analyze game state

• RuneLite HTTP API — reads exact skill levels, inventory, and equipment directly from the game client (no vision needed)

• Click coordinates — resolves pixel positions for inventory slots, sidebar tabs, and UI regions

• OSRS Wiki — item, NPC, quest, and page lookups

• Grand Exchange prices — real-time prices, history, and profit calculator

• Skill training tools — XP calculations and items-to-level planning

Setup

cp .env.example .env
# Edit .env — set ANTHROPIC_API_KEY and optionally VISION_PROVIDER

npm install
npm run build

Vision provider

The vision tools support two backends, configured via .env:

Option A — Anthropic API (default)

ANTHROPIC_API_KEY=your-api-key-here

Option B — Local AI via LM Studio (or any Anthropic-compatible server)

Your local model must be vision/multimodal capable (e.g. qwen2-vl-7b-instruct, gemma-4, llava). Text-only models cannot analyze screenshots.

VISION_PROVIDER=local
LOCAL_AI_BASE_URL=http://localhost:1234
LOCAL_AI_API_KEY=lmstudio
LOCAL_AI_DETAIL_MODEL=your-vision-model-name
LOCAL_AI_FAST_MODEL=your-vision-model-name
LOCAL_AI_THINKING=0   # set to 1 if your model supports reasoning

RuneLite HTTP Server plugin

The get_stats, get_inventory, and get_equipment tools read live game data directly from RuneLite without using vision. To enable them:

1. Open RuneLite → Plugin Hub → search HTTP Server → install and enable it

2. The plugin exposes http://localhost:8080/stats, /inv, and /equip

3. No extra configuration needed — the MCP connects on startup

These tools are more reliable and faster than their vision equivalents. Use them when you need ground-truth data (skill XP, exact item IDs, equipment slots).

macOS window capture

The screenshot tools use screencapture -l <CGWindowID> to capture just the RuneLite window. Window ID detection uses Swift + CGWindowListCopyWindowInfo — no extra tools required.

Fallback: If window ID detection fails, the full screen is captured. Vision analysis still works as long as RuneLite is visible.

Related MCP server: helix-pilot

Claude Desktop / Claude Code config

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "osrs": {
      "command": "node",
      "args": ["/absolute/path/to/osrs-mcp/dist/index.js"]
    }
  }
}

The server reads .env from the project root for ANTHROPIC_API_KEY / VISION_PROVIDER. You can also inline env vars in the config:

{
  "mcpServers": {
    "osrs": {
      "command": "node",
      "args": ["/absolute/path/to/osrs-mcp/dist/index.js"],
      "env": { "ANTHROPIC_API_KEY": "sk-..." }
    }
  }
}

Or with tsx for development (no build step needed):

{
  "mcpServers": {
    "osrs": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/osrs-mcp/src/index.ts"]
    }
  }
}

Tools

RuneLite HTTP API

Requires the HTTP Server plugin running on port 8080. Faster and more reliable than vision for these reads.

Screen capture

Vision analysis

Uses Claude vision (Opus for detail, Haiku for fast reads). Falls back to local model if VISION_PROVIDER=local.

Click coordinates

Returns pixel positions for UI elements. Layout is auto-detected from screenshot dimensions by default.

Layout detection: fixed mode is identified by the exact dimensions 765×503 (or 1530×1006 on Retina). All other sizes are treated as resizable. Resizable coordinates are edge-anchored (inventory to bottom-right, chat to bottom-left) and computed from the actual captured dimensions.

Tab names (top row): combat_options · skills · quests · inventory · equipment · prayer · magic
Tab names (bottom row): clan_chat · friends · account_management · logout · settings · emotes · music

OSRS Wiki

Grand Exchange

Utilities

Development

npm run dev       # Run directly via tsx (no build needed)
npm run build     # Compile TypeScript → dist/
npm run inspect   # Interactive tool tester via MCP Inspector
npm test          # Run test suite (vitest)
npm run test:watch  # Watch mode

Related

• RuneLite HTTP Server plugin

• OSRS Wiki API

• prices.runescape.wiki API

• MCP Inspector