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