Screeps World MCP Service

Integrates live Screeps server data directly into AI development workflows.

Features

Comprehensive API Coverage: Room operations, user data, market information, map analytics, and utilities
AI-Optimized: Enhanced responses with loop detection, caching, and completion indicators
Rate Limit Aware: Monitoring and guidance to prevent API limit issues
TypeScript: Full type safety with zod schema validation
MCP Protocol: Compatible with MCP-enabled clients

Setup

Install dependencies:

npm install

Configure your Screeps credentials:

cp .env.example .env
# Edit .env with your Screeps config

Build the project:

npm run build

Start the service:

npm start

Configuration

The service can be configured via environment variables or constructor parameters:

SCREEPS_BASE_URL: API base URL (defaults to official server)
SCREEPS_TOKEN: Your Screeps authentication token
SCREEPS_USERNAME: Your Screeps username (optional)

Getting Your Screeps Token

Go to Screeps Account Settings
Create a new auth token
Add it to your .env file

Development

Run TypeScript in watch mode:

npm run dev

Format code with Prettier:

npm run format

Usage Examples

After completing the setup, add to your mcp.json:

{
  "mcpServers": {
    "screeps-world": {
      "command": "node",
      "args": ["/path/to/screeps-world-mcp/dist/index.js"],
      "env": {
        "SCREEPS_TOKEN": "${env:SCREEPS_TOKEN}"
      }
    }
  }
}

AI Usage Guidelines

Follow Response Guidance: Each response includes completion indicators and suggested next steps
Avoid Redundant Calls: The server detects and warns against repetitive identical calls
Start with Resources: Get foundational data (version, shards) before using tools for specific queries
Respect Rate Limits: Monitor remaining API calls shown in responses

Available Resources

Resources provide static or server-wide data:

auth_me: Current authenticated user information
game_time: Current game time and tick information
world_size: World dimensions and size information
shards_info: Information about available shards
user_world_status: Current user world status and statistics
market_stats: Market statistics and trading information
version: API version and server information

Available Tools

Tools allow interactive queries with parameters:

Room Information

get_room_terrain: Get terrain information for a specific room
get_room_objects: Get objects and users in a specific room
get_room_overview: Get room overview and statistics
get_room_status: Get room status information

Market Information

get_market_orders_index: Get market orders index
get_my_market_orders: Get user's market orders
get_market_orders: Get market orders for a specific resource
get_money_history: Get user money transaction history

User Data

get_user_name: Get user name
get_user_stats: Get user statistics with optional interval
get_user_rooms: Get user rooms by user ID
find_user: Find user by ID or username
get_user_overview: Get user overview statistics with interval and stat filtering
get_user_memory: Get user memory data
execute_console_command: Execute console command in Screeps

Map & Analytics

get_map_stats: Get map statistics for specified rooms

Experimental Features

get_pvp_info: Get PvP information
get_nukes_info: Get active nukes information by shard

Utilities

calculate_distance: Calculate distance between two rooms
auth_signin: Sign in to Screeps to get authentication token

screeps-world-mcp