screeps-mcp-server by ralphschuler - MCP Server

Screeps API MCP Server

A Model Context Protocol (MCP) server that provides secure, validated tools for interacting with Screeps game servers. This server enables AI assistants and other MCP clients to connect to Screeps servers, execute console commands, retrieve game data, and manage memory segments with enhanced security and reliability.

Features

Core Functionality

Authentication: Connect to Screeps servers using username/password or API tokens (tokens recommended for security)
Secure Connection Initialization: Provide credentials once at startup to establish the single connection used by all tools
Console Commands & History: Execute JavaScript commands and retrieve recent console output with input sanitization
Live Console Streaming: Start, read, and stop a persistent websocket console stream with in-memory buffering
Memory Access: Read/write/delete arbitrary Memory paths and manage memory segments with validation
Room & Shard Data: Access room objects, terrain information, and shard metadata
User Information: Get account details and statistics for the authenticated player

Security & Reliability (NEW)

Input Validation: Comprehensive Zod schema validation for all tool parameters
Input Sanitization: Protection against XSS, command injection, and path traversal attacks
Rate Limiting: Configurable rate limiting to prevent API abuse (100 requests/minute default)
Error Handling: Structured error responses with proper context and logging
Type Safety: Full TypeScript coverage with eliminated any types
Configuration Management: Environment-aware configuration with security best practices
Logging: Structured logging with configurable levels and environment-specific settings

Installation (GitHub Packages)

This project is published via GitHub Packages, so npm must be configured to pull the @ralfschuler scope from npm.pkg.github.com. If you have not already, create (or update) your ~/.npmrc with a Personal Access Token that has the read:packages scope:

npm config set @ralfschuler:registry https://npm.pkg.github.com
echo "//npm.pkg.github.com/:_authToken=${GITHUB_PAT}" >> ~/.npmrc

Note: replace GITHUB_PAT with a GitHub Personal Access Token that includes the read:packages scope.

After configuration, install the CLI globally to place the screeps-api-mcp executable on your path:

npm install -g @ralfschuler/screeps-api-mcp

Running with npx

To execute the server without a global install, ensure the GitHub Packages registry configuration above is in place and then run:

npx @ralfschuler/screeps-api-mcp --token your-api-token-here

All of the CLI options shown below apply when running via npx as well.

Usage

Starting the Server

The MCP server communicates over stdio and requires authentication credentials to be provided on startup:

Using API Token (recommended):

screeps-api-mcp --token your-api-token-here

Using Username/Password:

screeps-api-mcp --username myuser --password mypass

Using Environment Variables:

export SCREEPS_TOKEN=your-api-token-here
screeps-api-mcp

All CLI Options:

screeps-api-mcp [options]

Options:
  --token <token>        Screeps API token
  --username <username>  Screeps username
  --password <password>  Screeps password
  --host <host>          Screeps server host (default: "screeps.com")
  --secure               Use HTTPS/WSS (default: true)
  --no-secure            Use HTTP/WS
  --shard <shard>        Default shard (default: "shard0")
  -h, --help             Display help

Configuration with MCP Clients

Add to your MCP client configuration (e.g., Claude Desktop):

Using API Token:

{
  "mcpServers": {
    "screeps-api": {
      "command": "screeps-api-mcp",
      "args": ["--token", "your-api-token-here"]
    }
  }
}

Using Environment Variables:

{
  "mcpServers": {
    "screeps-api": {
      "command": "screeps-api-mcp",
      "env": {
        "SCREEPS_TOKEN": "your-api-token-here"
      }
    }
  }
}

Environment Variables

Connection Settings

SCREEPS_TOKEN - Screeps API token (recommended for security)
SCREEPS_USERNAME - Screeps username
SCREEPS_PASSWORD - Screeps password
SCREEPS_HOST - Server hostname (default: screeps.com)
SCREEPS_SECURE - Use HTTPS/WSS (default: true)
SCREEPS_SHARD - Default shard (default: shard0)

Application Settings (NEW)

NODE_ENV - Environment mode: development, test, production
LOG_LEVEL - Logging level: debug, info, warn, error (default: info)
ENABLE_METRICS - Enable performance metrics collection (default: true in production)

Security Considerations

API Token Authentication (Recommended)

Use API tokens instead of username/password for better security
Generate tokens at: https://screeps.com/a/#!/account/auth-tokens
Tokens can be scoped to specific permissions and easily revoked

Input Validation & Sanitization

All inputs are validated against strict schemas before processing
Console commands are sanitized to prevent injection attacks
Memory paths are validated to prevent directory traversal
Room names must match valid Screeps format (E1S2, W1N1, etc.)

Rate Limiting

Built-in rate limiting prevents API abuse (100 requests/minute default)
Per-tool rate limiting with sliding window algorithm
Automatic cleanup prevents memory leaks

Available Tools

`screeps_connection_status`

Show connection details for the configured Screeps server, including console stream state.

Parameters:

None

`screeps_console_command`

Execute JavaScript code in the Screeps console.

Parameters:

command (string): JavaScript code to execute
shard (string): Target shard override (optional)

`screeps_console_history`

Retrieve recent console messages.

Parameters:

limit (number): Max messages to retrieve (default: 20, max: 200)

`screeps_console_stream_start`

Open a persistent websocket console stream and buffer messages in memory.

Parameters:

shard (string): Optional shard override
bufferSize (number): Max buffered messages (default: 500)

`screeps_console_stream_read`

Read buffered console messages captured by the live stream.

Parameters:

limit (number): Max messages to return (default: 50, max: 500)
since (number): Only include messages newer than this timestamp (ms)

`screeps_console_stream_stop`

Stop the live console stream and release the websocket connection.

Parameters:

None

`screeps_user_info`

Get information about the authenticated user.

Parameters:

None

`screeps_shards_info`

Fetch shard metadata from the server.

Parameters:

None

`screeps_room_objects`

Get all objects in a specific room.

Parameters:

roomName (string): Room name (e.g., "W1N1")

`screeps_room_terrain`

Get terrain data for a room.

Parameters:

roomName (string): Room name (e.g., "W1N1")

`screeps_memory_get`

Read a value from the Screeps Memory object.

Parameters:

path (string): Memory path (e.g., "stats.cpu")

`screeps_memory_set`

Write a value into the Screeps Memory object.

Parameters:

path (string): Memory path
value (string): Stringified JSON or raw string value to store

`screeps_memory_delete`

Remove a value from the Screeps Memory object.

Parameters:

path (string): Memory path to delete

`screeps_memory_segment_get`

Retrieve data from a memory segment.

Parameters:

segment (number): Segment number (0-99)

`screeps_memory_segment_set`

Store data in a memory segment.

Parameters:

segment (number): Segment number (0-99)
data (string): Data to store

Examples

Basic Usage Flow

Start the MCP server:

screeps-api-mcp --token your-api-token-here

Verify the authenticated connection:
```
screeps_connection_status
```
Start a live console stream and begin buffering logs:
```
screeps_console_stream_start with bufferSize=500
```

Execute console commands:

screeps_console_command with command="Memory.stats = { cpu: Game.cpu.getUsed() }"

Read the buffered stream output or request history:

screeps_console_stream_read with limit=20

screeps_console_history with limit=20

Inspect rooms or memory:

screeps_room_objects with roomName="E1S1"

screeps_memory_get with path="stats"

API Token Authentication

For enhanced security, use API tokens instead of passwords:

Generate a token at https://screeps.com/a/#!/account/auth-tokens

Start the MCP server with the token:

screeps-api-mcp --token your-api-token-here

Security & Error Handling

Enhanced Security Features

The server implements comprehensive security measures following MCP best practices:

Input Validation

Schema Validation: All tool parameters validated with Zod schemas
Type Safety: Full TypeScript coverage eliminates runtime type errors
Constraint Enforcement: Proper limits on string lengths, numeric ranges, and formats
Room Name Validation: Regex validation for Screeps room format (E1S2, W1N1, etc.)

Input Sanitization

XSS Prevention: HTML tags and dangerous JavaScript removed from inputs
Command Injection Protection: Dangerous patterns filtered from console commands
Path Traversal Prevention: Directory traversal attempts blocked in memory paths
SQL Injection Protection: Although not applicable here, string sanitization provides general protection

Rate Limiting & DoS Protection

Sliding Window Rate Limiting: 100 requests per minute default limit
Per-Tool Limiting: Individual rate limits for different tool types
Memory Management: Automatic cleanup prevents memory leaks from rate limiter
Graceful Degradation: Clear error messages when limits exceeded

Authentication Security

Token-Based Auth: API tokens recommended over username/password
Credential Validation: Comprehensive validation of authentication parameters
Secure Connection: HTTPS/WSS enforced by default
Configuration Sanitization: Sensitive data redacted from logs

Error Handling

The server provides structured error responses with proper context:

Authentication failures with clear remediation steps
Validation errors with specific field-level feedback
Network connectivity issues with connection status details
API rate limiting with retry guidance
Malformed requests with schema validation details
Configuration errors with environment variable guidance

Logging & Observability

Structured Logging: JSON-formatted logs with proper levels
Environment-Aware: Different log levels for development vs production
Error Context: Stack traces and request context in development mode
Performance Monitoring: Built-in metrics collection support
Security Audit: Request validation failures logged for monitoring

Development

Building from Source

git clone https://github.com/ralphschuler/screeps-api-mcp.git
cd screeps-api-mcp
npm install
npm run build

Testing

The project includes comprehensive test coverage with multiple testing approaches:

# Unit Tests
npm test              # Run all tests
npm run test:unit     # Run only unit tests
npm run test:coverage # Run tests with coverage report
npm run test:watch    # Run tests in watch mode

# Integration Tests (requires Docker or real Screeps server)
npm run test:integration  # Run integration tests
npm run test:docker      # Run tests with Docker Screeps server

# E2E Tests (interactive with MCP Inspector)
npm run test:e2e         # Launch MCP Inspector for E2E testing

See for detailed testing documentation and for MCP Inspector usage guide.

Development Workflow

npm run dev          # Build in watch mode
npm run lint         # Run ESLint
npm run lint:fix     # Fix linting issues
npm run format       # Format code with Prettier
npm start           # Run built version

Docker Development

Build and run with Docker:

# Build the image
docker build -t screeps-api-mcp .

# Run with environment variables
docker run --rm -e SCREEPS_TOKEN=your-token screeps-api-mcp --help

# Or use docker-compose
cp .env.example .env  # Edit with your credentials
docker-compose up screeps-api-mcp

CI/CD Pipeline

The project uses GitHub Actions for continuous integration:

CI Pipeline (ci.yml): Runs tests, linting, and builds on multiple Node.js versions
Docker Pipeline (docker.yml): Builds and publishes Docker images to GitHub Container Registry
Release Pipeline (release.yml): Automated releases with npm publishing and binary builds

All pushes and pull requests are automatically tested across Node.js 18, 20, and 22.

Deployment

Docker Deployment

GitHub Container Registry (Recommended):

docker pull ghcr.io/ralphschuler/screeps-api-mcp:latest
docker run --rm -e SCREEPS_TOKEN=your-token ghcr.io/ralphschuler/screeps-api-mcp:latest --help

Using Docker Compose:

# Copy and edit environment file
cp .env.example .env

# Run the service
docker-compose up -d screeps-api-mcp

Kubernetes Deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: screeps-api-mcp
spec:
  replicas: 1
  selector:
    matchLabels:
      app: screeps-api-mcp
  template:
    metadata:
      labels:
        app: screeps-api-mcp
    spec:
      containers:
        - name: screeps-api-mcp
          image: ghcr.io/ralphschuler/screeps-api-mcp:latest
          env:
            - name: SCREEPS_TOKEN
              valueFrom:
                secretKeyRef:
                  name: screeps-credentials
                  key: token
          resources:
            requests:
              memory: '64Mi'
              cpu: '100m'
            limits:
              memory: '256Mi'
              cpu: '500m'

Production Considerations

Use API tokens instead of username/password for better security
Set up monitoring and health checks
Consider rate limiting when connecting to official Screeps servers
Use container orchestration (Docker Swarm, Kubernetes) for high availability
Configure log aggregation for debugging

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please read for detailed guidelines on development setup, testing, and submitting pull requests.

Related Projects

screeps_console - Terminal console for Screeps
python-screeps - Python Screeps API client
Model Context Protocol - MCP specification and SDKs