World History Engine

You set up a World History Engine MCP Server to enable AI-assisted world simulation or standalone world generation. This server provides an HTTP endpoint for MCP clients and a local stdio interface for direct control, letting you query and mutate the world state or generate worlds from templates without external dependencies.

How to use

Connect your MCP client to the HTTP endpoint to use the AI-assisted world engine, or run the local stdio server to drive generation from the command line. Use the HTTP endpoint to interact with an external MCP client and the stdio interface to run the server locally and feed commands directly.

How to install

Prerequisites and setup steps ensure you can run the MCP server locally or in a container.

# Prerequisites
# Python 3.11+ and a runtime you prefer (uvx recommended)
# If deploying via Docker, Docker must be installed and running

# Optional: install uvx for local development
# (Follow your environment's typical installation process for uvx)

Additional configuration and usage notes

Two main MCP connection methods are described. Use the HTTP endpoint to expose the MCP server for remote clients. Use the stdio interface for a local, script-driven workflow.

{
  "mcpServers": {
    "world_builder": {
      "url": "http://0.0.0.0:8000",
      "type": "http"
    },
    "world_engine": {
      "command": "uv",
      "args": [
        "run",
        "mcp_server.py"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      },
      "type": "stdio"
    }
  }
}

Visualizing and exporting worlds

Generate a world using the GUI, CLI, or MCP, then use the built-in web visualizer to inspect the world state and timeline. Open the visualizer at the provided path and load your world export to explore relationships and events.

Templates, rules, and naming

The engine is data-driven. You can adjust generation rules, naming conventions, and world templates to customize factions, biomes, resources, and naming patterns.

Available tools

WorldGenerator

Generates world snapshots from YAML templates or predefined rules, producing a coherent world state

TemplateEditorService

Manages YAML templates for factions, biomes, and resources used in world generation

SimulationService

Runs time-based simulations to evolve world state across epochs

WorldQueryService

Provides queries to inspect world state, histories, and relationships

NamingService

Generates consistent names for entities based on naming rules