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 buildVision provider
The vision tools support two backends, configured via .env:
Option A — Anthropic API (default) ``env 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 reasoningRuneLite 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:
- Open RuneLite → Plugin Hub → search HTTP Server → install and enable it
- The plugin exposes
http://localhost:8080/stats,/inv, and/equip - 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.
---
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.
| Tool | Description | |------|-------------| | get_stats | All skill levels (base + boosted) and XP from /stats | | get_inventory | Inventory items — item ID, quantity, slot 0-27 — from /inv | | get_equipment | Equipped items by slot name (weapon, head, body…) from /equip |
Screen capture
| Tool | Description | |------|-------------| | find_osrs_window | Check if RuneLite is running and get its window ID | | capture_screen | Take a screenshot of the RuneLite window |
Vision analysis
Uses Claude vision (Opus for detail, Haiku for fast reads). Falls back to local model if VISION_PROVIDER=local.
| Tool | Description | |------|-------------| | analyze_screen | Analyze the screen with vision (focus: inventory / stats / chat / minimap / full / bank / shop / npc) | | analyze_inventory | List all items in the 28-slot inventory | | read_chat | Extract all visible chat messages | | read_stats | Read HP, Prayer, Run energy, Special attack from status bars | | read_minimap | Read compass bearing and nearby entity counts | | get_game_state | Full composite game state in one call | | detect_dialog | Read NPC dialog, option menus, or level-up popups | | detect_combat_state | Read combat indicators: XP drops, enemy HP bar, poison/venom, overhead prayers | | detect_loot | Identify ground items visible after a kill |
Click coordinates
Returns pixel positions for UI elements. Layout is auto-detected from screenshot dimensions by default.
| Tool | Description | |------|-------------| | detect_layout | Detect whether RuneLite is in fixed (765×503) or resizable mode | | get_tab_coords | Pixel coordinates to click a sidebar tab (prayer, inventory, skills, magic, combat_options, etc.) | | inventory_slot_coords | Pixel center of an inventory slot 0–27 | | get_clickable_regions | Bounding boxes for major UI panels: minimap, inventory, chat box, compass | | find_npc_on_screen | Locate a named NPC in the current screenshot, returns {screen_x, screen_y, confidence} | | find_object_on_screen | Locate an interactable object (bank chest, tree, ladder…), returns {screen_x, screen_y, confidence} |
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
| Tool | Description | |------|-------------| | wiki_search | Search the OSRS wiki | | wiki_page | Get the intro/summary of a wiki page | | wiki_item_info | Item details (alch values, members, weight, GE limit, etc.) | | wiki_npc_info | NPC details (combat level, HP, attack styles, aggressive/poisonous) | | wiki_quest_info | Quest details (difficulty, length, members, requirements, rewards) |
Grand Exchange
| Tool | Description | |------|-------------| | ge_price | Current GE price by item name or ID | | ge_price_history | Price chart data (timestep: 5m / 1h / 6h / 24h) | | ge_mapping | Full item name→ID mapping, filterable by name substring | | calculate_profit | Flip profit calculator — applies 1% GE tax, returns per-item and total profit + ROI |
Utilities
| Tool | Description | |------|-------------| | skill_xp_info | XP required for a target level, or current level from an XP value | | calc_items_to_level | How many actions/items to reach a target level given XP per action |
---
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---
