# World Model MCP

> World Model MCP is a free MCP server for knowledge and memory. Persistent 3D and 2D spatial world model for agents, with object permanence. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Free
- **Platforms:** CLI, self-hosted
- **Website:** https://worldmodelmcp.com
- **Repository:** https://github.com/putervision/world-model-mcp
- **MCP Registry name:** io.github.putervision/world-model-mcp
- **Categories:** knowledge and memory, developer tools
- **Listing updated:** 2026-11-16

## About

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.

## Features

- **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

## Install

### Claude Code (Terminal)

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

### Claude Desktop (claude_desktop_config.json)

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

### Cursor (~/.cursor/mcp.json)

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

### VS Code (.vscode/mcp.json)

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

### Windsurf (~/.codeium/windsurf/mcp_config.json)

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

### Other clients (your client's MCP settings (most use this shape))

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

## Tools

- `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.

## 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

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Ouroboros](https://ai-powered.com/mcp/ouroboros): Ouroboros is an open-source MCP server for developer tools.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.
- [Nautilus Compass Memory](https://ai-powered.com/mcp/nautilus-compass-memory): Nautilus Compass Memory is an open-source MCP server for knowledge and memory.

---
Source: https://ai-powered.com/mcp/world-model-mcp
