RELATED 01
State Memory MCP
Local SQLite graph of tasks, decisions and blockers that coding assistants keep across sessions
41GitHub stars
176/wknpm downloads
38popularity score
World Model MCP
A local SQLite store of 3D/2D entities, positions and relations for agents to query, simulate and plan on
By PuterVision TypeScript Local · stdio Knowledge and memoryDeveloper tools
34 popularity score ★ 21 ↓ 161/wk
Connect your client
Local (npm)
Add in one click
Opens the app, which asks before it adds the server.
Or add it by command or config
FirstTerminal
npm install -g @putervision/world-model-mcpClaude CodeTerminal
claude mcp add world-model -- world-model-mcp runClaude Desktopclaude_desktop_config.json
{
"mcpServers": {
"world-model": {
"command": "world-model-mcp",
"args": [
"run"
]
}
}
}Cursor~/.cursor/mcp.json
{
"mcpServers": {
"world-model": {
"command": "world-model-mcp",
"args": [
"run"
]
}
}
}VS Code.vscode/mcp.json
{
"servers": {
"world-model": {
"type": "stdio",
"command": "world-model-mcp",
"args": [
"run"
]
}
}
}Codex~/.codex/config.toml
[mcp_servers.world-model]
command = "world-model-mcp"
args = ["run"]Gemini CLITerminal
gemini mcp add --scope user world-model world-model-mcp -- runSettings 3
WORLD_MODEL_MCP_PROJECT |
Optional: Project id that scopes the stored world model; defaults to the current directory's name. |
|---|---|
WORLD_MODEL_STORAGE_DIR |
Optional: Folder for the SQLite databases; defaults to .world-model-mcp/ in the project. |
LOG_LEVEL |
Optional: Log verbosity: debug, info, warn or error. |
What it does
World Model MCP keeps a running spatial picture of a scene for an agent: named entities with 3D bounding boxes, positions, tags and a confidence score, plus relations between them such as on, inside, contains and near. Everything lives in a SQLite database inside the project folder, and no language model is involved in indexing or answering queries.
On top of that store it offers geometry helpers. An agent can search entities by text or by distance, predict a movement and check it for box collisions, plan a route around obstacles, ask what should be visible from a given pose and field of view, and fold vision detections back into the model. Entities that drop out of view are kept with a confidence that decays over time. It can also turn a planned path into timed WASD or arrow-key presses and screen coordinates for a Playwright script, though it only produces those inputs and presses nothing itself.
For longer work it adds snapshots with diff, undo and time travel, a shared blackboard with leases for several agents, spatial 'specs' that check clearance and containment, and SHA-256 evidence bundles tied to task ids. It is built to pair with the same maker's vision-memory and state-memory servers but runs on its own.
The v0.6.1 source registers 15 tools, as the README says. Not in the README: every time the server starts with `run`, it runs the same setup as `world-model-mcp init` (src/index.ts calls runAutoInit). That creates `.world-model-mcp/`, appends to `.gitignore`, writes or updates CLAUDE.md, `.agents/AGENTS.md`, `.windsurfrules`, `.github/copilot-instructions.md` and Cursor, VS Code and Gemini rule files in the project, merges an entry into `.cursor/mcp.json` and `.vscode/mcp.json`, and edits home-directory files such as `~/.cursorrules` and the Claude Desktop config when those apps' folders exist (src/cli/init.ts).
What it needs
| Runtime | Node.js 18+ |
|---|
Node.js 18.18.0 or later with npm. The package is installed globally (`npm install -g @putervision/world-model-mcp`) so the `world-model-mcp` command is on PATH. No account, API key or network service is needed. The server works on the folder it is started in (or the project named by WORLD_MODEL_MCP_PROJECT), so start it from the project directory.
Limits
It sees nothing itself: positions and detections come from the agent or another server. generate_game_inputs returns key timings and screen coordinates but presses no keys; a separate Playwright setup must run them. By default queries return up to 50 entities (`limit`), compact slices hold 16, get_expected_view uses a 90-degree, 100-unit view and wait_for_spatial_state stops after 10000 ms (src/tools/definitions.ts). manage_snapshot restore and undo overwrite live state and cannot be reversed unless a snapshot was saved first. Starting the server rewrites agent instruction and MCP config files (see About).
Who it suits
Suits developers building agents for 3D games, simulations, robotics experiments or browser game automation who want a deterministic local record of where things are, with collision and visibility checks, instead of coordinates in the prompt. It reaches no outside service. It is a poor fit for general text memory across sessions; a memory server fits that better. Since starting it edits CLAUDE.md, AGENTS.md, editor rules and MCP configs, run it where those changes can be reviewed. We also hold a different project of the same name (saravananjaichandar/world-model-mcp, a Python package); it is a separate server.
Tools 15
update_entity- Create or partially update an entity: position, 3D bounds, tags, properties, status and confidence.
query_entities- Find entities by full-text search, radius around a point, status or tags, optionally with their change history.
set_relation- Add or remove a spatial link between two entities, such as on, inside, contains or near.
get_spatial_map- Export the scene as JSON, GeoJSON, glTF, OBJ, a summary or a compact nearest-entity slice.
simulate_movement- Predict a move with box collision checks, or plan waypoints around obstacles.
ingest_observation- Merge vision detections into the model, matching them to known entities by distance.
get_expected_view- List what should be visible from an observer pose and field of view, accounting for occlusion.
link_to_goal- Tie entities or regions to a task id and fetch the spatial context around a goal.
record_outcome- Log the result of an action: moved, changed or destroyed entities, singly or in batches.
manage_spatial_spec- Register clearance, bounds and containment contracts and score the scene against them.
create_evidence_pack- Bundle spatial checks into a SHA-256 hashed evidence record linked to a task.
use_spatial_blackboard- Post and read topics, take or release leases, and flag conflicting intents between agents.
manage_snapshot- Save, list, diff and restore checkpoints, undo mutations or view a past state.
wait_for_spatial_state- Poll until an entity exists, is active, passes a confidence level or enters a region.
generate_game_inputs- Turn a path into timed key presses for Playwright, or convert between 3D points and screen pixels.