Skip to content
MCP server

World Model MCP

Persistent 3D and 2D spatial world model for agents, with object permanence

Runs locallyStatus and history
Install
Pricing
Free
Platforms
CLI, self-hosted
Runs
Locally
Version
0.6.1
Listing updated
1 day ago

About World Model MCP

World Model MCP is a free MCP server for knowledge and memory. It runs locally on your machine and is started by your AI client.

World Model MCP gives an agent a durable memory of where things are. Entities are stored with 3D positions, orientations, bounding boxes, properties and tags in a local SQLite database, and linked by spatial relations such as inside, on, next to and above, with path traversal over the resulting graph. Nothing uses an LLM for the spatial indexing, and all data stays in a .world-model-mcp folder in your workspace.

Object permanence is the distinctive part: entities stay in memory when out of view, with configurable exponential confidence decay and a lifecycle from active to hidden to lost. Movement simulation predicts trajectories and tests box collisions before an action runs, and a frustum calculation says what an observer should see from a given pose, so observations can be diffed for appeared or moved items.

The README counts 15 consolidated tools, a Playwright generator for timed keyboard input in 3D games, multi-agent blackboard coordination, spatial design contracts with SHA-256 evidence bundles and a Three.js visualizer. It needs Node 18.18 or newer.

Install

Run in a terminal

claude mcp add world-model-mcp -- npx -y @putervision/world-model-mcp

Add to claude_desktop_config.json

{
  "mcpServers": {
    "world-model-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@putervision/world-model-mcp"
      ]
    }
  }
}
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "world-model-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@putervision/world-model-mcp"
      ]
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

Add to .vscode/mcp.json

{
  "servers": {
    "world-model-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@putervision/world-model-mcp"
      ]
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "world-model-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@putervision/world-model-mcp"
      ]
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "mcpServers": {
    "world-model-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@putervision/world-model-mcp"
      ]
    }
  }
}

Tools this server provides (8)

Taken from the project documentation; the running server may differ.

update_entity
Creates or updates an entity with position, orientation, bounds and properties.
query_entities
Searches entities by keyword, proximity, tags, status or history.
set_relation
Records or removes spatial relationships.
get_spatial_map
Exports the spatial layout as JSON, GeoJSON, glTF, OBJ or summary.
simulate_movement
Predicts trajectories and tests collisions or computes waypoints.
ingest_observation
Ingests perception detections and reconciles the frustum view.
get_expected_view
Computes expected visible entities from an observer pose.
generate_game_inputs
Generates Playwright keyboard input sequences for game navigation.

What it does

Durable entity tracking
Stores positions, orientation and bounds in local SQLite.
Spatial relations graph
Links entities with inside, on, near and similar relations.
Object permanence
Keeps unseen entities with decaying confidence.
Movement simulation
Predicts trajectories and collisions before acting.
View frustum projection
Computes what an observer should see and diffs observations.
Game input generation
Creates timed WASD key sequences for Playwright.
Local 3D visualizer
Browser-based Three.js view of the world model.

Good for

  • Give an agent persistent memory of a scene's layout
  • Check a planned movement for obstacles
  • Detect which objects appeared or moved between observations
  • Generate keyboard inputs for navigating a 3D game
  • Coordinate several agents around shared spatial state

Pricing

Free

Free to install from npm

Prices change. Check worldmodelmcp.com before you buy.

World Model MCP FAQ

Does it use an LLM?

No. Spatial indexing and queries are deterministic and use SQLite with FTS5.

Where is data stored?

Locally in .world-model-mcp inside your workspace.

How do I install it?

Run npm install -g @putervision/world-model-mcp, then world-model-mcp init in your project.

How many tools are there?

15 consolidated tools across spatial memory, simulation, goals, spatial specs and multi-agent replay.

Is World Model MCP free?

Yes. World Model MCP is free to use.

How do I add World Model MCP to Claude Code?

Run this command in your terminal: claude mcp add world-model-mcp -- npx -y @putervision/world-model-mcp

What are the best alternatives to World Model MCP?

The closest alternatives to World Model MCP are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.

Alternatives to World Model MCP

  1. REA

    MCP server

    CLI and MCP server that lets coding agents reverse engineer apps and binaries

    Runs locally
    • Open source
    • 464K GitHub stars
    • Developer tools
  2. Codebase Memory

    MCP server

    Local MCP server that builds a code knowledge graph for AI coding agents

    Runs locally
    • Open source
    • 48.7K GitHub stars
    • Knowledge and memory
  3. GitHub

    MCP server

    Official MCP server connecting AI assistants to GitHub repos, issues and workflows

    Not checked yet
    • Remote
    • Open source
    • 34.5K GitHub stars
    • Developer tools
  4. MCP toolkit giving coding agents symbol-level code retrieval and editing

    Runs locally
    • Open source
    • 31.5K GitHub stars
    • Developer tools
  5. XERJ

    MCP server

    Local search engine for AI agents with cited answers over your code and docs

    Runs locally
    • Open source
    • 19.2K GitHub stars
    • Knowledge and memory
  6. Ouroboros

    MCP server

    Spec-first layer that pins requirements and verifies results of AI coding agent work

    Runs locally
    • Open source
    • 6.4K GitHub stars
    • Developer tools