🎮 RS3-MCP - Professional RuneScape Automation Server

A production-ready implementation of the Model Context Protocol (MCP), providing AI agents (like Claude and ChatGPT) with high-fidelity tools to interact with the RuneScape 3 and OSRS ecosystems.

[!NOTE] This project is forked and significantly enhanced from stefanxyz/mcp-server-runescape.

🚀 Enhancements & Modernization

While the core API interactions were established by stefanxyz, this repository features comprehensive enterprise-grade improvements:

• 🛡️ Full Validation Suite: Includes a rigorous automated testing framework (Vitest) for API stability.
• 🛡️ Error Resilience: Enhanced error handling and fallback logic for unreliable RuneScape endpoints.
• 🛡️ Performance Audit: Detailed benchmarking and optimization reports for low-latency tool execution.
• 🛡️ Agentic Integration: Specific optimizations for "Cursor" and "Claude Desktop" environments.

✨ Core Tools

The server provides 6 essential tools for AI-driven gameplay analysis:

1. 💰 get_item_details: Real-time Grand Exchange prices and 180-day trends.
2. 📈 get_item_price_history: Historical data visualization for market analysis.
3. 🏆 get_player_hiscore: Deep-dive into player ranks, XP, and activity scores.
4. 🥇 get_top_rankings: Skill-specific leaderboards and competitive analysis.
5. 👥 get_player_count: Real-time server population tracking.
6. 📋 get_rsuser_total: Global account creation and historical growth metrics.

📦 Getting Started

1. Requirements

• Node.js 18+
• MCP Client (Claude Desktop, Cursor, etc.)

2. Configuration (Claude Desktop)

Paste this into your claude_desktop_config.json:

{
  "mcpServers": {
    "rs3-mcp": {
      "command": "node",
      "args": ["F:/Software Developement/Portfolio/Games/rs3bot/mcp-server-runescape/src/server.js"]
    }
  }
}

🛠️ Testing & Validation

We maintain a detailed log of system health:

• API_VALIDATION_REPORT.md: Comprehensive endpoint status.
• PERFORMANCE_OPTIMIZATION_SUMMARY.md: Latency benchmarks.
• MCP_CONNECTION_VALIDATION_SUMMARY.md: Client-side handshake verification.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details. Original core logic © 2025 stefanxyz. Enhancements and validation suite © 2026 Ross Ward.

---

Developed & Validated by Ross Ward 📡🛰️🌎