MCP Server Runescape

1# mcp-server-runescape
2[![npm version](https://badge.fury.io/js/mcp-server-runescape.svg)](https://badge.fury.io/js/mcp-server-runescape)
3[![smithery badge](https://smithery.ai/badge/@stefan-xyz/mcp-server-runescape)](https://smithery.ai/server/@stefan-xyz/mcp-server-runescape)
4 
5This is an MCP server with tools for interacting with RuneScape (RS) and Old School RuneScape (OSRS) data, including item prices, player hiscores, and more.
6 
7https://github.com/user-attachments/assets/7c141575-443b-4b76-8b33-6d48ec82fbe7
8 
9## Features
10 
11The MCP server provides several tools which are used to answer your questions during gaming with data from accurate sources.
12 
13### 1. Item Details (`get_item_details`)
14 
15Retrieve comprehensive information about tradeable items, including:
16 
17- Current price in the Grand Exchange
18- Price trends (24h, 30, 90, and 180 days)
19- Name
20- Category
21- Description (examine text)
22- Image
23- Members
24- ID
25 
26https://runescape.wiki/w/Application_programming_interface#detail
27 
28### 2. Item Price History (`get_item_price_history`)
29 
30Access the price history of an item over the last 180 days, including:
31 
32- Price on a given day (timestamp)
33- Average price on a given day (timestamp)
34 
35https://runescape.wiki/w/Application_programming_interface#Graph
36 
37### 3. Player Hiscore (`get_player_hiscore`)
38 
39Fetch rankings and experience for skills and activities of any player, including:
40 
41- Player rank
42- Skill level
43- Experience points
44- Activity scores
45 
46https://runescape.wiki/w/Application_programming_interface#Hiscores_Lite_2
47 
48### 4. Top Rankings (`get_top_rankings`)
49 
50View the top (max 50) players for a specific skill or activity, including:
51 
52- Name
53- Score (used for both skill and activity)
54- Rank
55 
56https://runescape.wiki/w/Application_programming_interface#ranking
57 
58### 5. Player Count (`get_player_count`)
59 
60Gets the number of players currently online in RuneScape and Old School RuneScape, including:
61 
62- Real-time player counts
63 
64https://runescape.wiki/w/Application_programming_interface#player_count
65 
66### 6. Account Totals (`get_rsuser_total`)
67 
68Gets the current amount of accounts created that can access any form of RuneScape. This includes accounts made on FunOrb or a particular version of RuneScape, including:
69 
70- Historical accounts creation data
71 
72https://runescape.wiki/w/Application_programming_interface#rsusertotal
73 
74#### Note
75 
76For consistency I tried to only use API endpoints which support both RS and OSRS data.
77 
78## Example Use Cases
79 
80The goal is for you to have an easy way to fetch more accurate data right from the source while scaping.
81 
82Here are some example queries you can ask the AI when using this MCP server:
83 
84### Item Details
85 
86```
87"What is the price of a dragon scimitar in the Grand Exchange?"
88"Torva full helm price"
89"Current price of a dragon pickaxe"
90"How much percentage has the price of a dragon pickaxe changed in the past 30 days?"
91"How much percentage has the price of a dragon pickaxe changed in the past 90 days?"
92"How much percentage has the price of a dragon pickaxe changed in the past 180 days?"
93"Give me the description of an armadyl godsword"
94"Give me the icon of a dragon scimitar"
95"What is the id of an abbyssal whip?"
96```
97 
98### Item Price History
99 
100```
101"Give me the price history of a dragon scimitar"
102"Rune scimitar price on 1 april 2025?"
103```
104 
105### Player Hiscore
106 
107```
108"What rank is Zezima?"
109"What rank is Zezima on runescape?"
110"How much experience does Lynx Titan have overall?"
111"Iron Hyger ironman rank?"
112```
113 
114### Top Rankings
115 
116```
117"Top 10 players overall?"
118"Give me the top 50 attack rankings"
119"Number one agility on runescape?"
120"Most zulrah kills?"
121"Give me the top 5 jad rankings"
122```
123 
124## Getting Started
125 
126[Introduction to MCP servers](https://modelcontextprotocol.io/introduction)
127 
128You can use the MCP server in many clients, for example:
129 
130- Claude desktop
131- Cursor
132 
133### 1. Add the MCP server in your config (NPM Package)
134 
135Paste this snippet in your mcp config that your client is using
136 
137```json
138{
139  "mcpServers": {
140    "mcp-server-runescape": {
141      "command": "npx",
142      "args": ["-y", "mcp-server-runescape"]
143    }
144  }
145}
146```
147 
148You can find the config file in (mac):
149 
150- Claude desktop:
151 
152`~/Library/Application Support/Claude/claude_desktop_config.json`
153 
154- Cursor:
155 
156`/Users/name/.cursor/mcp.json`
157 
158### 2. From Source
159 
160**Required** [Node.js](https://nodejs.org/en) installed on your system
161 
1621. Clone this repository
1632. Install dependencies:
164   ```bash   
165   yarn
166   ```
167   or
168   ```bash   
169   npm install
170   ```
1713. Then update your Claude desktop or Cursor with:
172   ```json
173   {
174     "mcpServers": {
175       "mcp-server-runescape": {
176         "command": "node",
177         "args": ["/Users/path/to/mcp-server-runescape/src/server.js"]
178       }
179     }
180   }
181   ```
1824. **Optional**: Run the debugger/inspector
183   ```bash
184   yarn dev
185   ```
186   or
187   ```bash   
188   npm run build
189   ```
190 
191Make sure to:
192 
193- Replace `/path/to/mcp-server-runescape` with the actual path to your installation.
194 
195After updating the configuration, restart Claude desktop or Cursor for the changes to take effect.
196 
197#### Personal preference
198 
199You can use any client you want, my personal preference goes to Cursor at the moment in combination with deepseek-v3.1 which is performing really well.
200 
201[List of clients](https://modelcontextprotocol.io/clients)
202 
203## API Documentation
204 
205For detailed information about the Runescape API endpoints used by this MCP server, visit:
206[RS/Wiki API](https://runescape.wiki/w/Application_programming_interface)
207 
208## Thank you
209 
210I built this over the weekend, to learn a bit more about MCP servers. Runescape was the perfect subject to try it out on.
211 
212- Shout out to the rs/wiki team for the docs and API.
213 
214If this helps you out in anyway when scaping and you would like to support me, feel free to
215 
216[!["Buy Me A Coffee"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://buymeacoffee.com/stefanxyz)
217