Screeps World MCP Service

You can run and connect to a live Screeps world data source through an MCP server to power AI workflows. This server exposes a wide API over room data, markets, map analytics, user info, and more, with type safety, caching, and rate‑limit guidance to keep your AI agents efficient and reliable.

How to use

Connect your MCP client to the Screeps World MCP Server to start querying live Screeps data. You’ll configure a local MCP process and point your client at it, then request data through the available resources and tools. Use the setup to fetch foundational information first, such as version and shard details, before making targeted queries about rooms, markets, or user data.

How to install

Prerequisites you need before starting are Node.js and npm. Ensure they are installed on your system.

# 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

Additional sections

Configuration is handled through environment variables or constructor parameters. The following options are available: SCREEPS_BASE_URL for the API base URL, SCREEPS_TOKEN for your Screeps authentication token, and SCREEPS_USERNAME as an optional username. You will typically provide your Screeps token to authorize data access.

Getting your Screeps token involves creating a new auth token in your Screeps account settings and adding it to your environment configuration.

An example MCP client configuration is shown here. This registers a local stdio MCP server that runs the Screeps World MCP code and uses your token from the environment.

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

Security and maintenance

Keep your Screeps token secure. Do not commit tokens into version control. Rotate tokens periodically and scope access to only what you need for AI workflows.

Notes and troubleshooting

If you encounter rate-limit warnings, use the built‑in guidance to adjust request patterns. The server provides completion indicators and caching to optimize response times and avoid redundant calls.

Token and setup help

If you need to reconfigure credentials, edit the .env file or re-run the configuration steps to update SCREEPS_TOKEN and related values.

Known resources and available data

The server exposes a broad set of endpoints for static or server-wide data, including authentication info, game time, world size, shard info, user world status, market statistics, and API version details.

Example usage with MCP client configuration

After configuring, you can start using the API to fetch data about rooms, markets, and users through the available tools and resources in your MCP client.

Available tools

auth_me

Fetch information about the currently authenticated user, including basic profile data and status.

game_time

Retrieve the current game time, tick information, and related timing data for synchronization.

world_size

Get the dimensions and size information of the Screeps world to understand space constraints.

shards_info

Obtain information about available shards and their status for cross-shard queries.

user_world_status

Get the current user’s world status and statistics, including active rooms and usage metrics.

market_stats

Query market statistics and trading information to understand supply/demand trends.

version

Return API version and server information for compatibility checks.

get_room_terrain

Request terrain information for a specific room to understand navigateability and hazards.

get_room_objects

List objects and other users present in a specific room.

get_room_overview

Get a high-level overview and statistics for a room.

get_room_status

Obtain status information about a room, including operational state and resources.

get_market_orders_index

Fetch the index of market orders to understand current order depth.

get_my_market_orders

Retrieve your own market orders to review active bids and asks.

get_market_orders

Get market orders for a specific resource to assess availability and pricing.

get_money_history

Access your money transaction history for auditing and planning.

get_user_name

Query the authenticated user’s display name.

get_user_stats

Get user statistics with optional time interval for trend analysis.

get_user_rooms

List rooms owned or controlled by the user.

find_user

Find a user by ID or username for reference or collaboration.

get_user_overview

Get overview statistics for a user with optional interval and stat filtering.

get_user_memory

Retrieve user memory data for debugging and profiling.

execute_console_command

Execute a console command in Screeps to perform live actions.

get_map_stats

Get map analytics and statistics for specified rooms.

get_pvp_info

Fetch PvP information to assess combat-related data.

get_nukes_info

Get active nukes information by shard for security and planning.

calculate_distance

Calculate the distance between two rooms for routing and planning.

auth_signin

Sign in to Screeps to obtain a fresh authentication token.