wiseoldman-mcp

An MCP server that wraps the Wise Old Man OSRS stat-tracking API (https://docs.wiseoldman.net/api), exposing it as tools for MCP-compatible clients (Claude Code, Claude Desktop, etc).

Covers the full documented API surface: players, groups, competitions, records, deltas, name changes, and efficiency (EHP/EHB) — 54 tools total, all prefixed wom_.

Setup

npm install
npm run build

Optionally copy .env.example to .env and set WOM_API_KEY (raises the rate limit from 20 to 100 requests/60s — request one in the WOM Discord). Mutating actions (create/edit/delete groups & competitions) don't need this key; they use a per-resource verificationCode returned when you create that resource.

Running locally

npm run dev          # run directly with tsx, no build step
npm run inspector     # open the MCP Inspector against the server for manual testing

Register with Claude Code

claude mcp add wiseoldman -- node /path/to/wiseoldman_mcp/dist/index.js

(Run npm run build first so dist/index.js exists. Re-run the build after pulling changes.)

Register with Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "wiseoldman": {
      "command": "node",
      "args": ["/path/to/wiseoldman_mcp/dist/index.js"],
      "env": { "WOM_API_KEY": "..." }
    }
  }
}

Project layout

• src/womClient.ts — thin fetch wrapper around the WOM REST API (auth headers, error normalization). Nothing here is MCP-specific.

• src/enums.ts — reference lists (skills, bosses, periods, etc) baked into tool descriptions. Kept as plain strings rather than strict zod enums, since WOM adds new bosses/activities over time — the live API remains the source of truth for validation.

• src/toolHelpers.ts — shared result/error formatting for tool handlers.

• src/tools/*.ts — one file per API resource, each registering its tools on the McpServer instance.

• src/index.ts — wires everything together and connects over stdio.

Roadmap: remote hosting with OAuth (Authentik)

Right now this only runs locally over stdio, which is fine for a single user's local clients. Deploying it as a shared/remote server later will need:

• Swapping StdioServerTransport for the SDK's StreamableHTTPServerTransport, run behind an actual HTTP server (e.g. Express/Hono).

• An OAuth layer in front of it (the MCP spec expects OAuth 2.1 with PKCE for remote servers) — Authentik can act as the authorization server; the transport setup would validate the bearer token per-request against Authentik's introspection/JWKS endpoint.

• The wom client and all tool registration code is transport-agnostic already, so none of src/tools/* or src/womClient.ts should need to change — only src/index.ts and a new auth-checking layer around it.

Not implemented yet — flagging so the current structure doesn't need rework when we get there.