Guide · Cursor + MCP

Give Cursor a map of your codebase

Cursor's built-in codebase indexing is embedding search — good at "find something like this text", blind to structure. It can't tell you who imports a file, what a change would break, or which files are load-bearing. The fix is structural: index the repository once into a code knowledge graph, and let Cursor query it over MCP — it pulls the exact neighborhood a task touches instead of reading everything.

Setup — two commands

1
Install the CLI
One global install gives you the indexer, the MCP server, and the local viewer.
```
npm install -g openvisio
```
2
Set up the repo
Run the bare command inside your project. It writes the project-scoped MCP config (.cursor/mcp.json), runs a first index, and prints next steps.
```
cd your-project && openvisio
```
3
Approve the server in Cursor
Open the project in Cursor and enable the "openvisio" server under Settings → MCP. Cursor reads the project-scoped .cursor/mcp.json that the setup command wrote.
4
Watch it work (optional)
Run the viewer with spotlight on, and every file the agent queries lights up on a live 3D map of the repo, in real time.
```
openvisio view
```

What Cursor can ask the graph

Once connected, the agent has six structured queries instead of blind file reads: resolve_context (a task-ranked skeleton plus the relevant neighborhoods, every line with a path:line anchor), find_symbol, get_dependents, get_neighborhood, get_hotspots, and get_repo_skeleton. Discovery stops being a token sink and becomes a lookup.

Your code stays on your machine

Indexing is deterministic — tree-sitter parses the repository into files, symbols, imports, and calls, and PageRank ranks what matters. No LLM ever sees your code during indexing, nothing is uploaded, and the whole thing runs on your machine.

What it saves

Exploring an unfamiliar repository routinely burns 50,000+ tokens before any real work begins, and most agents re-send every opened file on every turn. With the graph, Cursor asks "what does this task touch?" and reads only the answer — in practice 30–90× fewer tokens on discovery-heavy tasks. The long-form math is in our token-cost guide.

Frequently asked questions

Does OpenVisio work with Cursor out of the box?

Yes — Cursor speaks MCP, and the bare `openvisio` command writes the project-scoped config (.cursor/mcp.json) for you. Approve the server once and the tools appear in the agent's toolkit.

Does indexing send my code anywhere?

No. Indexing is deterministic tree-sitter parsing on your machine — no LLM, no network. The MCP server serves the graph locally.

How is this different from letting the agent grep?

Grep finds text; the graph knows structure. "Who imports this file", "what is the ranked skeleton of this repo", and "what neighborhood does this task touch" are one query each against the pre-computed graph — with grep they are dozens of reads, re-paid every session.

How is this different from Cursor's own @codebase index?

Cursor indexes embeddings for semantic text search. OpenVisio indexes structure — imports, calls, dependents, centrality. The two answer different questions, and Cursor agents can use both side by side.

See it on your repo

Paste a GitHub URL or open a folder — the map builds in your browser in seconds.

Try it free

or npm install -g openvisio for the MCP server