RuneScape Wiki MCP Server
A Model Context Protocol (MCP) server that provides access to RuneScape Wiki APIs, including real-time Grand Exchange prices, item data, and player statistics for RuneScape 3 (RS3).
Features
- Real-time Grand Exchange Prices: Get current, 5-minute, and 1-hour average prices for all items
- Item Database: Access complete item mappings with metadata (names, IDs, examine text, etc.)
- Price Time Series: Historical price data with configurable time intervals
- Player Statistics: Lookup player stats from RuneScape 3 hiscores
- Multiple Game Modes: Support for normal, ironman, and hardcore ironman accounts
- MCP Resources: Direct access to price and item data through MCP resource URIs
Installation
Prerequisites
- Node.js 18.0.0 or higher
- npm or yarn
Install Dependencies
npm install
Build the Project
npm run build
Development Mode
npm run dev
This will start the TypeScript compiler in watch mode and automatically restart the server when files change.
Usage
With Claude Desktop
Add the following configuration to your Claude Desktop config file:
{
"mcpServers": {
"runescape-wiki": {
"command": "node",
"args": ["/path/to/runescape-wiki-mcp/dist/index.js"]
}
}
}
With MCP Inspector
Test the server using the MCP Inspector:
# Using npm script (recommended)
npm run inspector
# Or manually with npx
npx @modelcontextprotocol/inspector node dist/index.js
Quick Test
Verify the server is working correctly:
npm test
Available Tools
get_latest_prices
Get the latest Grand Exchange prices for all items or a specific item.
Parameters:
itemId(optional): Item ID to get price for specific item
Example:
{
"itemId": 4151
}
get_item_mapping
Get the complete mapping of all items with their IDs, names, and metadata.
Parameters: None
Returns: Array of items with:
id: Item IDname: Item nameexamine: Examine textmembers: Whether it's a members-only itemlowalch: Low alchemy valuehighalch: High alchemy valuelimit: Grand Exchange buy limitvalue: Item valueicon: Icon filename
get_5m_prices
Get 5-minute average prices for all items.
Parameters:
timestamp(optional): Unix timestamp to get prices for specific time
get_1h_prices
Get 1-hour average prices for all items.
Parameters:
timestamp(optional): Unix timestamp to get prices for specific time
get_timeseries
Get price time series data for a specific item.
Parameters:
itemId(required): Item ID to get time series fortimestep(required): Time interval - one of:5m,1h,6h,24h
Example:
{
"itemId": 4151,
"timestep": "1h"
}
get_player_stats
Get player statistics from RuneScape 3 hiscores.
Parameters:
username(required): Player username to lookupgameMode(optional): Game mode - one of:normal,ironman,hardcore
Example:
{
"username": "Zezima",
"gameMode": "normal"
}
Returns: Parsed statistics including:
- Overall rank and total level
- Individual skill levels, experience, and ranks
- Formatted data for all 30 skills (including Summoning, Dungeoneering, Divination, Invention, Archaeology, and Necromancy)
Item Category Mapping
| Category Name | Category Number |
|---|---|
| Ammo | 1 |
| Arrows | 2 |
| Bolts | 3 |
| Construction materials | 4 |
| Cooking ingredients | 5 |
| Costumes | 6 |
| Crafting materials | 7 |
| Familiars | 8 |
| Fletching materials | 9 |
| Food and Drink | 10 |
| Herblore materials | 11 |
| Hunting equipment | 12 |
| Jewellery | 13 |
| Mage armour | 14 |
| Mage weapons | 15 |
| Melee armour - low | 16 |
| Melee armour - mid | 17 |
| Melee armour - high | 18 |
| Melee weapons - low | 19 |
| Melee weapons - mid | 20 |
| Melee weapons - high | 21 |
| Mining and Smithing | 22 |
| Potions | 23 |
| Prayer armour | 24 |
| Prayer materials | 25 |
| Range armour | 26 |
| Range weapons | 27 |
| Runecrafting | 28 |
| Runes, Spells, Teleports | 29 |
| Seeds | 30 |
| Summoning scrolls | 31 |
| Tools and containers | 32 |
| Woodcutting product | 33 |
| Pocket items | 34 |
| Stone spirits | 35 |
| Firemaking products | 36 |
| Archaeology materials | 37-43 |
Refer to this table when using tools that require a category number, such as search_items.
Available Resources
runescape://prices/latest
Direct access to the latest Grand Exchange prices for all items.
runescape://items/mapping
Direct access to the complete item mapping data.
API Endpoints
This server uses the following RuneScape Wiki APIs:
- RS3 Prices API:
https://prices.runescape.wiki/api/v1/rs- Latest prices, 5-minute averages, 1-hour averages, time series data
- RS3 Hiscores API:
https://secure.runescape.com/m=hiscore- Player statistics for different game modes
Rate Limits
The RuneScape Wiki APIs have the following guidelines:
- Use a descriptive User-Agent (automatically handled by this server)
- Avoid excessive requests that could impact API stability
- The server implements proper error handling and respects API limitations
Error Handling
The server includes comprehensive error handling:
- API request failures are caught and returned as error responses
- Invalid parameters are validated before making API calls
- Network timeouts and connection issues are handled gracefully
- Player not found errors are properly reported
Development
Project Structure
src/
├── index.ts # Main server implementation
├── types/ # TypeScript type definitions
└── utils/ # Utility functions
dist/ # Compiled JavaScript output
Scripts
npm run build: Compile TypeScript to JavaScriptnpm run watch: Watch for changes and recompilenpm start: Start the server in production modenpm run dev: Start in development mode with auto-restartnpm test: Run a simple test to verify the server is workingnpm run inspector: Launch the MCP Inspector to test the server
Adding New Tools
- Define the tool in the
toolsarray with proper schema - Add a case handler in the
CallToolRequestSchemahandler - Implement the API logic with proper error handling
- Update this README with documentation
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
License
MIT License - see LICENSE file for details.
Acknowledgments
- RuneScape Wiki for providing the APIs
- Model Context Protocol for the MCP specification
- Jagex for RuneScape 3
Support
For issues, questions, or feature requests, please open an issue on the GitHub repository.
Note: This is an unofficial tool and is not affiliated with Jagex or the RuneScape Wiki. Please respect the API usage guidelines and terms of service.