World Model MCP — Claude Code MCP server: what it does & setup
Maintains deterministic 2D and 3D spatial memory for AI agents, calculates collision-free navigation, and tracks occluded objects using confidence decay.
claude mcp add world-model-mcp -- npx -y @putervision/world-model-mcpWhat World Model MCP 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.
What it helps with
- 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 for the agent
- 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.
How to install World Model MCP
Platform CLI
claude mcp add world-model-mcp -- npx -y @putervision/world-model-mcpPlatform CLI
codex mcp add putervision-world-model-mcp -- npx -y @putervision/world-model-mcpConfig file
{
"mcpServers": {
"putervision-world-model-mcp": {
"command": "npx",
"args": [
"-y",
"@putervision/world-model-mcp"
]
}
}
}Config file
{
"servers": {
"putervision-world-model-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@putervision/world-model-mcp"
]
}
}
}Platform CLI
gemini mcp add putervision-world-model-mcp npx -y @putervision/world-model-mcpStep by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about World Model MCP
How to install World Model MCP in Claude Code?
Run claude mcp add world-model-mcp -- npx -y @putervision/world-model-mcp in your terminal.
What does World Model MCP do?
It acts as a local 2D and 3D spatial database for autonomous agents. It resolves entity occlusion, predicts physical collisions, and supplies compact local context slices.
What are the runtime requirements for World Model MCP?
It requires Node.js version 18.18.0 or higher. All entity records, relations, and snapshots stay locally in the .world-model-mcp/ workspace folder.
