Cursor + Open Kioku MCP

Give Cursor an evidence layer before it edits your codebase

Open Kioku is a local MCP server Cursor reads before it edits: it shows its evidence — files, streams, confidence, caveats — declares an edit boundary in a plan, and has its diff verified against that plan. Open Kioku does not upload source.

Start setup View on GitHub

4-Step Setup

From zero to evidence-backed edits in four local steps.

Install the CLI, index your repo, connect MCP to Cursor, and paste the golden prompt. The Open Kioku commands run locally.

1
Install Open Kioku

Install the CLI globally with npm. The wrapper pulls the native binary for your OS automatically (macOS, Linux, Windows).
terminal
```
$npm install -g open-kioku
```
Other channels: cargo install open-kioku-cli or cargo binstall open-kioku-cli from crates.io; binaries with checksums, an SBOM, and provenance on GitHub releases.
2
Index your repo

Build the local index — files, symbols, imports, tests, and graph edges — all stored under .ok/ in your repo. Open Kioku does not send the index to a hosted service.
terminal
```
$ok index .
# Scans files → parses symbols → builds graph → indexes for search
# Local indexes: .ok/index.sqlite + .ok/search/tantivy
```
3
Connect MCP to Cursor

Shortcut: one command indexes the repository, writes a repository-scoped .cursor/mcp.json plus managed guidance, and checks that the local server answers an MCP initialize request (run without --apply to preview; nothing is written).
terminal
```
$ ok setup agent cursor --repo . --apply
```
Or generate the MCP server entry for Cursor manually and paste it into your Cursor MCP settings:
terminal
```
$ok mcp install cursor --repo .
```
How to paste: Open Cursor → Settings (⌘ ,) → search "MCP" → click "Edit in mcp.json" → paste the JSON below and save.
mcp.json
```
{
  "open-kioku": {
    "command": "ok",
    "args": [
      "mcp",
      "serve",
      "--repo",
      "/absolute/path/to/repo",
      "--read-only"
    ]
  }
}
```

Paste the golden prompt

Add this prompt to your Cursor chat or .cursorrules file. It tells the agent to use Open Kioku's plan-before-edit workflow every time.

.cursorrules

Use Open Kioku before editing. Check repo_status, search_code, get_definition,
get_references, impact_analysis, and find_tests_for_change. Build a plan with
plan_change first, then edit, and verify after the edit with verify_change.

What You Get

MCP tools Cursor can call after setup.

Every tool runs locally against the index you built in Step 2. Read-only by default. No hosted index or embeddings service required.

What to expect: on a Java repository of about ten thousand files the right file is in the top five about half the time and in the context pack about two thirds of the time; on a TypeScript repository of about nine hundred files, in the pack nearly nine in ten and in the top five about four in five. That is the retrieval floor before exact lookups and the plan → verify loop; it is re-measured nightly against frozen baselines. Numbers and method.

plan_change

Build an evidence-backed edit plan with primary context, impact candidates, validation targets, and boundary policy.

verify_change

After the edit, verify that changes stayed inside the plan boundaries and flag any drift or unintended side effects.

search_code

BM25 full-text search over your codebase. Returns ranked snippets with file paths, line ranges, and confidence scores.

impact_analysis

Trace callers, dependents, and affected modules using the local symbol graph. Know what breaks before you touch it.

get_definition

Jump to the definition of any symbol — function, class, type, or constant — from the indexed symbol table.

get_references

Find every reference to a symbol across the codebase. Uses persisted graph edges, not text grep.

find_tests_for_change

Surface the test files and test functions most relevant to a planned change, before the agent starts editing.

repo_status

Get a snapshot of the indexed repository — file counts, symbol counts, index freshness, and health signals.

build_context_pack

Assemble a focused context bundle from search results, symbols, and graph data for the agent's next edit.

Local & Private

Built for codebases people cannot upload.

✓ All indexes stored locally under .ok/
✓ No cloud API or embeddings service
✓ MCP stdio transport — no open ports
✓ Read-only by default
✓ Source edits stay in your normal editor
✓ No source upload by Open Kioku

Back to openkioku.com