convez.ai
MCP ServerIntegração & APIsAvançado
Sleepywalker69

OSRS MCP Companion

Sleepywalker69/OSRS-MCP-Companion

Ponte de dados de jogo em tempo real entre RuneLite e assistentes de IA via MCP

Ver no GitHub
InicialPluginScore · de 0 a 100

Plugin RuneLite que expõe dados de jogo em tempo real via API HTTP local, emparelhado com servidor MCP que concede aos assistentes de IA (Claude Desktop, Claude Code) acesso direto a 57 ferramentas de estado do jogo. Permite consultar qualquer dado do Old School RuneScape em tempo real através de integração com Claude.

Instalação

$npx convez-ai Sleepywalker69/OSRS-MCP-Companion

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
4
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
v1.0.1
Issues abertas
0
Contribuidores
9

Casos de uso

  • Análise de estado do jogo e debug assistido por IA
  • Automação de tarefas repetitivas em OSRS com acesso a dados vivos
  • Pesquisa e engenharia reversa de mecânicas de jogo

Veredito

Implementação técnica sofisticada e bem-documentada que cria um canal bidirecional entre jogo e IA. Nicho específico (OSRS), mas exemplo sólido de extensão de aplicativo desktop via MCP — útil para quem estuda padrões de integração ou automação em jogos.

README

A tradução para o português deste README ainda está na fila.


A RuneLite plugin that exposes live game data via a local HTTP API, paired with an MCP server that gives AI assistants (Claude Desktop, Claude Code, etc.) direct access to 57 game state tools. Think IDA for Old School RuneScape — connect via MCP and query any data you need in real time.

What It Does

  1. RuneLite Plugin — Runs a local HTTP API server (default http://127.0.0.1:8085) inside RuneLite with 53 endpoints covering every aspect of game state.
  2. MCP Server — A TypeScript MCP server (mcp-server/) that wraps all HTTP endpoints as 57 MCP tools with rich descriptions for intuitive AI prompting.
  3. File Sync — Periodically saves player snapshots to JSON files for offline use.

All data stays on your machine. The API only binds to localhost.

MCP Tools (57 total)

The MCP server provides tools across eight categories:

Live Game State (16 tools)

ToolWhat it does
game_stateLogin status, world, tick count, player location
live_playerHealth, prayer, run energy, animation, combat target
live_skillsReal-time skill levels and XP
live_inventoryCurrent inventory contents
live_equipmentCurrently worn gear
live_bankBank contents (must be open in-game)
nearby_npcsNPCs near player, filterable by name/ID
nearby_playersOther visible players
nearby_objectsGame objects (trees, rocks, doors, etc.)
ground_itemsItems on the ground
menu_entriesCurrent right-click menu options
cameraCamera position and angles
tile_infoCollision flags at specific coordinates
pluginsLoaded RuneLite plugins and config
player_appearanceEquipment, body kits, colors, gender
chatRecent chat messages — game, public, private, clan. Filterable by type and count

Interfaces & Widgets (4 tools)

ToolWhat it does
interfacesAll currently open game interfaces
inspect_widgetRead a specific widget group's children and properties
find_item_in_interfaceSmart search — finds an item by name in any open container (shop, bank, trade). Supports fuzzy matching: "d scim" finds "Dragon scimitar"
dialogCurrent NPC/player dialogue — text, speaker name, selectable options, continue button state

Game Definitions (6 tools)

ToolWhat it does
lookup_itemItem definition by ID or name search
lookup_npcNPC definition by ID or name search
lookup_objectObject definition by ID or name search
lookup_varbitVarbit definition (varp index, bit range)
lookup_enumEnum definition (key-value pairs)
lookup_structStruct definition (param values)

DevTools (9 tools)

ToolWhat it does
read_varbitRead current varbit value(s)
read_varpRead current varp value(s)
var_historyRecent varbit/varp changes with old/new values
recent_interactionsRecent clicks and hovers — "what did I just click?"
graphics_objectsActive visual effects (spell impacts, etc.)
active_prayersCurrently active prayers and prayer points
xp_trackerSession XP gains per skill
loot_logSession loot drops, filterable by NPC
raw_actionsMulti-layer action capture — tracks menu clicks, CS2 script callbacks, and inferred state changes. Detects actions that bypass the normal menu system

Debug & Recording (8 tools)

ToolWhat it does
debug_snapshotInstant full combat state snapshot — player, NPCs, prayers, inventory, equipment, recent interactions, effects. One call does it all
start_recordingStart recording game events for a duration (default 3 min, max 10 min). Filter by event type to keep the buffer focused
stop_recordingStop an active recording early
recording_statusCheck recording progress — events captured, time remaining, active filter
get_recordingRetrieve recorded timeline (tick-grouped format v2) with filtering by event type and tick range
bufferTick-level state history with delta encoding — query what changed in the last N ticks. Stores ~10 min of per-tick snapshots. Supports filtering by entity type, name, and ID
screenshotCapture the game viewport as a PNG image
runelite_logsRead RuneLite console/plugin logs — filter by level, logger name, or search text

19 recordable event types: game_tick, hitsplat, animation_changed, npc_spawned, npc_despawned, actor_death, var_changed, menu_clicked, stat_changed, item_changed, interacting_changed, object_spawned, object_despawned, projectile_spawned, gfx_created, chat_message, sound_effect, loot_received, game_state_changed

Recording presets (pass to start_recording types parameter):

  • Boss (full): game_tick,hitsplat,animation_changed,npc_spawned,npc_despawned,actor_death,menu_clicked,object_spawned,object_despawned,projectile_spawned,gfx_created,sound_effect,chat_message,loot_received,game_state_changed
  • Combat (full): game_tick,hitsplat,npc_spawned,npc_despawned,actor_death,menu_clicked,object_spawned,object_despawned,projectile_spawned,gfx_created,sound_effect
  • Combat (lite): game_tick,hitsplat,actor_death,menu_clicked,projectile_spawned
  • Vars only: var_changed,game_tick
  • Clicks/movement: menu_clicked,game_tick

Wiki & Prices (3 tools)

ToolWhat it does
searchSearch the OSRS Wiki
summaryGet a Wiki page summary
priceGrand Exchange price lookup

Synced Player Data (10 tools)

ToolWhat it does
list_synced_playersList players with locally saved data
get_my_profileFull player summary from saved data
get_my_bankSaved bank contents (searchable)
get_my_statsSaved skill levels and XP
get_my_questsSaved quest states
get_my_equipmentSaved equipment
get_my_inventorySaved inventory
get_my_diariesSaved achievement diary status
get_my_combat_achievementsSaved combat achievement status
playerFetch player data via WikiSync API

Prerequisites

  • Node.js 18+ — required to run the MCP server
  • Java 11+ (JDK) and Node.js 18+ — only needed if building from source

Quick Start (Recommended)

Download the latest release from the Releases page. You'll find two files:

  • osrs-companion-<version>-all.jar — the RuneLite plugin
  • osrs-mcp-server-<version>.zip — the MCP server

1. Install the RuneLite Plugin

  1. Open RuneLite and go to Configuration (wrench icon) → RuneLite plugin settings
  2. Scroll down and enable "Enable sideloaded plugins" (requires Developer Mode — launch RuneLite with --developer-mode if the option isn't visible)
  3. Copy osrs-companion-<version>-all.jar to your RuneLite plugins folder:
    • Windows: %USERPROFILE%\.runelite\plugins\
    • macOS/Linux: ~/.runelite/plugins/
  4. Restart RuneLite — the OSRS MCP Companion plugin will appear in the plugin list

2. Set Up the MCP Server

  1. Extract osrs-mcp-server-<version>.zip to a permanent folder (e.g. C:\osrs-mcp\ or ~/osrs-mcp/)
  2. Open a terminal in that folder and install dependencies:
    npm install --production
    
  3. Note the full path to dist/index.js inside the extracted folder — you'll need it in the next step

3. Configure MCP

The MCP server connects AI assistants to the plugin's HTTP API. Configure it for whichever client you use:

Claude Desktop

Add to %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "osrs-companion": {
      "command": "node",
      "args": ["C:\\osrs-mcp\\dist\\index.js"],
      "env": {
        "OSRS_API_URL": "http://127.0.0.1:8085"
      }
    }
  }
}

Replace C:\\osrs-mcp\\dist\\index.js with the actual path to dist/index.js in your extracted folder. Restart Claude Desktop after saving.

Claude Code

claude mcp add osrs-companion node /path/to/osrs-mcp/dist/index.js

Or add it manually to .claude/settings.json:

{
  "mcpServers": {
    "osrs-companion": {
      "command": "node",
      "args": ["/path/to/osrs-mcp/dist/index.js"],
      "env": {
        "OSRS_API_URL": "http://127.0.0.1:8085"
      }
    }
  }
}

Other MCP Clients

Any MCP-compatible client can connect. The server uses stdio transport. Set OSRS_API_URL if the plugin runs on a non-default port (default: http://127.0.0.1:8085).

4. Try It

With RuneLite running and the plugin enabled, ask Claude things like:

  • "What's in my inventory?"
  • "Find the knife in the shop"
  • "What NPCs are near me?"
  • "What did I just click?"
  • "How much XP have I gained this session?"
  • "What's the price of an Abyssal whip?"
  • "Why is it stuck? Debug this" (instant snapshot)
  • "Record the next 3 minutes while I run the script"
  • "What happened? Show me the recording"
  • "What does the NPC say?" (reads dialogue text and options)
  • "Take a screenshot" (captures game viewport as PNG)
  • "What changed in the last 5 ticks?" (delta-encoded state history)
  • "Any errors in the RuneLite console?" (reads plugin logs)
  • "What chat messages came in?" (reads recent chat)
  • "Show me raw actions — anything bypass the menu?" (multi-layer action capture)

Building from Source

Requires Java 11+ JDK and Node.js 18+.

git clone https://github.com/Sleepywalker69/OSRS-MCP-Companion.git
cd OSRS-MCP-Companion

RuneLite plugin:

# Run directly in RuneLite dev mode
./gradlew run          # Linux/macOS
.\gradlew.bat run      # Windows

# Or build a JAR
./gradlew shadowJar    # output: build/libs/osrs-companion-*-all.jar

MCP server:

cd mcp-server
npm install
npm run build          # output: mcp-server/dist/

Live API Endpoints

All 53 endpoints available at http://127.0.0.1:8085:

EndpointDescription
GET /List all endpoints with descriptions
GET /api/game-stateLogin state, tick count, FPS, world
GET /api/playerCurrent player state
GET /api/locationDetailed location with region IDs
GET /api/skillsAll skill levels and XP
GET /api/inventoryInventory contents
GET /api/equipmentEquipment slots
GET /api/bankBank contents
GET /api/questsQuest states
GET /api/npcsNearby NPCs. ?name=X or ?id=X to filter
GET /api/playersNearby players
GET /api/objects?radius=NNearby game objects
GET /api/ground-items?radius=NGround items
GET /api/widgetsActive widget groups
GET /api/widget?group=XWidget group contents
GET /api/interfacesOpen interfaces with visibility
GET /api/menu-entriesCurrent menu entries
GET /api/varbit?id=XVarbit values
GET /api/varp?id=XVarp values
GET /api/var-historyRecent var changes. ?type=varbit|varp, ?last=N
GET /api/interaction-historyRecent clicks and hovers. ?last=N
GET /api/graphics-objectsActive visual effects
GET /api/item-def?id=XItem definition. ?name=X for search
GET /api/npc-def?id=XNPC definition. ?name=X for search
GET /api/obj-def?id=XObject definition. ?name=X for search
GET /api/varbit-def?id=XVarbit definition
GET /api/struct-def?id=XStruct definition
GET /api/enum-def?id=XEnum definition
GET /api/player-appearancePlayer appearance. ?name=X for others
GET /api/chatRecent chat messages. ?type=X, ?last=N
GET /api/dialogCurrent NPC/player dialogue state
GET /api/screenshotCapture game viewport as PNG (Content-Type: image/png)
GET /api/bufferTick-level state history. ?t=N, ?types=npc,player,skills,hits, ?names=X, ?ids=X
GET /api/logsRuneLite console logs. ?level=INFO|WARN|ERROR, ?logger=X, ?search=X, ?last=N
GET /api/actionsMulti-layer action tracker. ?last=N, ?source=menu|script|inferred, ?search=X
GET /api/cameraCamera position and angles
GET /api/sceneScene base coords and map regions
GET /api/tile?x=X&y=YTile collision flags
GET /api/pluginsLoaded RuneLite plugins
GET /api/plugin-config?plugin=XPlugin configuration
GET /api/xp-trackerSession XP gains
GET /api/lootSession loot drops. ?npc=X to filter
GET /api/projectilesActive projectiles
GET /api/wiki/search?q=XWiki search proxy
GET /api/wiki/page-info?title=XWiki page info proxy
GET /api/wiki/parse?title=XWiki page parse proxy
GET /api/prayersActive prayers and prayer points
POST /api/recording/start?duration=NStart recording events (seconds, default 180, max 600)
POST /api/recording/stopStop recording
GET /api/recording/statusRecording state and progress
GET /api/recording/dataRecorded events. ?types=X, ?from_tick=X&to_tick=Y, ?last=N
GET /api/eventsServer-Sent Events stream

Standalone GUI Window

Click the Open GUI button in the RuneLite sidebar to launch a standalone 1100×720 window with 8 data tabs, a nav rail, live header status pills, and a footer status bar. Supports standard minimize/maximize/close window controls. The sidebar stays slim — just a brand header, the launch button, and a compact live-status block.

Keyboard shortcuts: Ctrl+1-8 to switch tabs, Esc to close (state preserved, reopen from sidebar).

TabWhat it shows
DashboardTwo-column layout: player status bars (HP, prayer, run, spec) on the left; API server status, session summary, and quick action buttons (Save, Snapshot, Screenshot) on the right
RecordStart/stop event recording with duration and event type selection. Includes presets (Boss, Combat, Lite, Vars, Clicks), a live progress bar, and a recorded events viewer with Load Events and Copy All buttons. Recordings auto-save to gzipped JSON (tick-grouped format v2) on stop — click Reveal file to open the recordings folder
ActionsLive feed of the ActionTracker — menu clicks, CS2 script callbacks, and inferred state changes. Filterable by source and searchable. Copy button for clipboard export
ChatReal-time chat viewer with type filtering (Game, Public, Private, Clan) and search. Color-coded by chat type. Copy button for clipboard export
LogsRuneLite console log viewer with level filtering (ERROR/WARN/INFO/DEBUG) and search. Stack traces on hover
StatsSession XP tracker with per-skill gains and XP/hr rates. Loot log with NPC grouping and item details. Copy button for clipboard export
VarsVarbit/varp change timeline — shows recent variable changes with type badges (orange for varbits, blue for varps), tick numbers, old/new values with human-readable var names. Filterable and searchable by ID. Exclude filters let you hide noisy varps/varbits by ID (comma-separated). Copy button for clipboard export
BufferTick-level state buffer viewer with delta encoding. Shows entity spawns/despawns, HP changes, skill gains, and hitsplats between ticks

Configuration

API Server

  • Enable API Server: Toggle the HTTP API on/off (default: on)
  • API Port: Port number (default: 8085, requires restart to change)

File Export

  • Save Interval: How often to write JSON snapshots to disk (default: 60s)
  • Data Toggles: Enable/disable syncing for each data category

File Sync

Player snapshots are saved periodically to:

~/.runelite/osrs-companion/{username}.json

Event recordings are auto-saved as gzipped JSON (format v2: tick-grouped) when stopped:

~/.runelite/osrs-companion/recordings/recording_{timestamp}.json.gz

Recording Format v2

Recordings use a tick-grouped format that organizes events chronologically by game tick. This reduces token usage by ~30% compared to flat event arrays while preserving all data.

{
  "format": 2,
  "meta": {
    "startTick": 83, "endTick": 212,
    "durationTicks": 129, "totalEvents": 4120,
    "eventCounts": { "hitsplat": 157, "game_tick": 39, ... }
  },
  "ticks": [
    {
      "tick": 85, "ts": 1780088760830,
      "fps": 50,
      "player": { "position": {"x":3427,"y":3541,"plane":2}, "health": 99, "prayer": 12, ... },
      "nearbyNpcs": [ ... ],
      "events": [
        {"type": "hitsplat", "target": {"name":"Gargoyle"}, "amount": 6, "hitsplatType": 17, ...},
        {"type": "animation_changed", "actor": {"name":"Gargoyle"}, "animation": 1517}
      ]
    }
  ]
}
  • game_tick data (player snapshot, FPS, nearby NPCs) is promoted to tick-level fields
  • tick, timestamp, ticksElapsed are not repeated on every event — they live on the tick wrapper
  • eventType is shortened to type on each event
  • All original event fields are preserved with no data loss

Privacy

  • The API server binds to 127.0.0.1 only (not accessible from the network)
  • JSON files are saved to local disk only
  • No data is sent to any external server, API, or third party
  • You control what gets synced via the config panel

License

BSD 2-Clause "Simplified" License. See LICENSE.

Ver o original no GitHub

Bom para

Relacionados