# World Model MCP

Maintains deterministic 2D and 3D spatial memory for AI agents, calculates collision-free navigation, and tracks occluded objects using confidence decay.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 20
- Author: putervision
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/putervision/world-model-mcp
- Updated: 2026-10-03
- HTML: https://affpapa.org/en/nevibecode/mcp/putervision-world-model-mcp

## What it does

The server stores spatial state in a local SQLite WAL database under `.world-model-mcp/`. Spatial queries remain deterministic. Lookups use FTS5 text search and 3D Euclidean distances without prompting an LLM. To reduce context load, it provides compact observer-relative slices containing up to 16 closest items in less than one kilobyte.

Its 15 tools handle entity state tracking, bounding box collision checks, and field-of-view occlusion culling. Object permanence relies on an exponential decay model. When an object leaves the view cone, its status shifts from active to hidden and eventually to lost. For browser automation, the server outputs timed WASD keyboard hold durations in milliseconds for Playwright.

Without Node.js version 18.18.0 or higher, the package will not run. Developers can inspect axes, bounding boxes, and topological links directly in a browser via the Three.js visualizer using `world-model-mcp view`.

## Requirements
- Needs: Node.js (commands run via npx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add world-model-mcp -- npx -y @putervision/world-model-mcp
```

### Codex

**Platform CLI**
```bash
codex mcp add putervision-world-model-mcp -- npx -y @putervision/world-model-mcp
```

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "putervision-world-model-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@putervision/world-model-mcp"
            ]
        }
    }
}
```

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "putervision-world-model-mcp": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@putervision/world-model-mcp"
            ]
        }
    }
}
```

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add putervision-world-model-mcp npx -y @putervision/world-model-mcp
```

## When to use it
- Persist entity coordinates and 3D bounding boxes across agent runs
- Predict obstacle-free navigation paths using AABB collision detection
- Output precise WASD keyboard hold timings for Playwright browser automation
- Coordinate parallel subagents using topic blackboards with mutex locks

## Example prompts
- Check the container position in the room and route around nearby obstacles.
- Generate timed WASD keypress sequences to guide the character toward the goal.
- Take a spatial state snapshot and return a compact slice of nearby entities.

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md