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

1. Install dependencies:

npm install

2. Configure your Screeps credentials:

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

3. Build the project:

npm run build

4. 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

1. Go to Screeps Account Settings

2. Create a new auth token

3. 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

1. Follow Response Guidance: Each response includes completion indicators and suggested next steps

2. Avoid Redundant Calls: The server detects and warns against repetitive identical calls

3. Start with Resources: Get foundational data (version, shards) before using tools for specific queries

4. 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