sqlite-graph-mcp
Stores and queries the code/spec graph in a local SQLite database file, with nodes and edges represented as rows for deterministic traversal and direct inspection using SQLite tooling.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@sqlite-graph-mcp Where is walkGraph defined and which files import it?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
sqlite-graph-mcp
A code & spec graph your AI agent can actually cite — no embeddings, no Docker, no Neo4j, no API key.
One SQLite file, five operators, file:line evidence for every answer.
npx -y sqlite-graph-mcp index
npx -y sqlite-graph-mcp plan 'find "walker" kind=symbol | walk type=defines dir=in depth=1 | filter kind=file'
# → src/graph/walker.ts:1Most "code graph" tools ask you to run an embedding pipeline, push your source to a vector
database, and then return semantically similar chunks you still have to verify. This one builds a
small, deterministic graph in a local SQLite file during index, and answers structural questions
with recursive CTEs. When the agent says "this file defines walkGraph, and index.ts imports
it", the claim comes with a path and a line number.
Why a graph in SQLite
Deterministic. The same workspace produces the same graph. Nothing depends on a model, a chunking strategy, or a similarity threshold.
Zero infrastructure.
node:sqlite-class storage viabetter-sqlite3, one file at.sqlite-graph/index.db,.gitignore-friendly. No daemon, no container, no account.Fast enough to re-index on every commit. A few thousand files index in well under a second.
Auditable. Every node is a row, every edge is a row. You can open the database with
sqlite3and check the agent's reasoning yourself.Citations by construction. Nodes carry
pathandline; edges carry the line of the import/definition/link that created them.
Related MCP server: CodeGraph MCP
What it indexes
Node kind | Source | Example key |
|
|
|
| top-level | let |
| Markdown |
|
|
|
|
Edge type | Meaning |
| file → file (static |
| file → symbol (declaration is exported) |
| file → symbol, file → heading, |
| Markdown link/reference → file or heading, including |
| file → package, package → dependency from the manifest |
Files are tagged (code, ts, doc, test, entry, manifest, exported, …), and tags are
filterable — that is how graph_orphans can skip test and entry files without extra arguments.
Install
Requires Node.js 20+ (tested on 20 and 22). better-sqlite3 ships prebuilt binaries.
# run without installing
npx -y sqlite-graph-mcp --help
# or install globally
npm install -g sqlite-graph-mcp
# or as a dependency
npm install sqlite-graph-mcpMCP setup
The server speaks MCP over stdio. --root is the workspace to index; it defaults to the
process's current directory, which is usually what an MCP client gives you.
Claude Code
claude mcp add sqlite-graph -- npx -y sqlite-graph-mcp serve --root /absolute/path/to/repoCursor (~/.cursor/mcp.json)
{
"mcpServers": {
"sqlite-graph": {
"command": "npx",
"args": ["-y", "sqlite-graph-mcp", "serve", "--root", "/absolute/path/to/repo"]
}
}
}Codex (~/.codex/config.toml)
[mcp_servers.sqlite-graph]
command = "npx"
args = ["-y", "sqlite-graph-mcp", "serve", "--root", "/absolute/path/to/repo"]Claude Desktop (claude_desktop_config.json)
{
"mcpServers": {
"sqlite-graph": {
"command": "npx",
"args": ["-y", "sqlite-graph-mcp", "serve", "--root", "/absolute/path/to/repo"]
}
}
}From a local clone (no registry needed):
{
"mcpServers": {
"sqlite-graph": {
"command": "node",
"args": ["/absolute/path/to/sqlite-graph-mcp/dist/bin/cli.js", "serve", "--root", "/absolute/path/to/repo"]
}
}
}The first tool call indexes the workspace automatically if .sqlite-graph/index.db is missing.
Re-run graph_index after large refactors; it rebuilds the graph in one transaction.
The five operators
Operator | Tool | Question it answers |
|
| "Where is |
|
| "What does this file import, transitively?" |
|
| "Of these nodes, which are docs under |
|
| "Which files are never imported or linked?" |
|
| "Chain the above and give me citations." |
graph_find
FTS5 prefix ranking plus a substring/glob fallback, so index still finds GraphIndexer and
*.test.ts works as a glob.
// graph_find { "query": "emoji", "kind": "symbol" }
{
"count": 1,
"nodes": [
{
"id": 12,
"key": "symbol:src/greet.ts#greetEmoji",
"kind": "symbol",
"name": "greetEmoji",
"citation": "src/greet.ts:5",
"snippet": "export const greetEmoji = '👋';",
"tags": ["symbol", "exported", "variable"]
}
]
}graph_walk
Traversal is a recursive CTE over edges. Cycle protection is path-based: a branch stops when
the next id already appears in the path it travelled, so a → b → a terminates at depth 1 even
with maxDepth=20.
WITH RECURSIVE walk(id, depth, path) AS (
SELECT id, 0, ',' || id || ',' FROM nodes WHERE id IN (?, ?)
UNION ALL
SELECT e.dst, w.depth + 1, w.path || e.dst || ','
FROM walk w
JOIN edges e ON e.src = w.id
WHERE w.depth < :maxDepth
AND instr(w.path, ',' || e.dst || ',') = 0
AND e.type IN ('imports', 'links_to')
)
SELECT id, MIN(depth) AS depth FROM walk GROUP BY id ORDER BY depth, id;// graph_walk { "start": ["file:src/index.ts"], "edgeType": "imports", "direction": "out" }
{
"count": 5,
"nodes": [
{ "key": "file:src/index.ts", "depth": 0, "citation": "src/index.ts:1" },
{ "key": "file:src/greet.ts", "depth": 1, "citation": "src/greet.ts:1" },
{ "key": "file:src/graph/walker.ts", "depth": 1, "citation": "src/graph/walker.ts:1" },
{ "key": "file:src/graph/cycle-a.ts", "depth": 2, "citation": "src/graph/cycle-a.ts:1" },
{ "key": "file:src/graph/cycle-b.ts", "depth": 3, "citation": "src/graph/cycle-b.ts:1" }
]
}Direction in finds dependents ("who breaks if I rename this?"), both finds the neighbourhood.
graph_filter
// graph_filter { "ids": [12, 20, 21], "kind": "symbol", "prefix": "src/graph/", "tag": "exported" }
{ "count": 2, "nodes": [ /* WalkOptions, walkGraph */ ] }Predicates: kind, notKind, path (glob), prefix, suffix, name, regex, tag, limit.
graph_orphans
Set difference in one query: files with no inbound imports/links_to edge, and symbols that
are never exported. Test and entry files are excluded unless you ask for them.
{
"files": [{ "path": "src/legacy.ts", "citation": "src/legacy.ts:1" }],
"symbols": [{ "name": "unusedHelper", "citation": "src/index.ts:13" }],
"counts": { "files": 1, "symbols": 2 }
}graph_plan — chain them
A plan is a pipeline. Each step consumes the previous step's node set; find starts a new set.
find "walker" kind=symbol | walk type=defines dir=in depth=1 | filter kind=fileThe same plan as JSON (what an LLM or a script would send):
{
"steps": [
{ "op": "find", "query": "walker", "kind": "symbol" },
{ "op": "walk", "edgeType": "defines", "direction": "in", "maxDepth": 1 },
{ "op": "filter", "predicate": { "kind": "file" } }
],
"limit": 50
}Response (trimmed):
{
"count": 1,
"nodes": [{ "key": "file:src/graph/walker.ts", "citation": "src/graph/walker.ts:1", "depth": 1 }],
"edges": [{ "src": 20, "dst": 22, "type": "defines", "citation": "src/graph/walker.ts:7" }],
"citations": ["src/graph/walker.ts:1"],
"steps": [
{ "index": 0, "op": "find", "inputCount": 0, "outputCount": 1 },
{ "index": 1, "op": "walk", "inputCount": 1, "outputCount": 2 },
{ "index": 2, "op": "filter", "inputCount": 2, "outputCount": 1 }
],
"explain": [
"find(\"walker\", kind=symbol) → 1 nodes",
"walk(from 1, in, defines, depth=1) → 2 nodes",
"filter({\"kind\":\"file\"}) 2 → 1 nodes"
],
"truncated": false
}Pipeline syntax:
Step | Options |
|
|
|
|
|
|
| subtract another find from the current set |
CLI
The same engine is usable without an MCP client:
sqlite-graph-mcp index [dir] # build/rebuild the graph
sqlite-graph-mcp find "walkGraph" --kind symbol
sqlite-graph-mcp walk <id|key> --type imports --dir out --depth 3
sqlite-graph-mcp plan 'find "graph" | walk type=imports depth=2'
sqlite-graph-mcp orphans --include-tests
sqlite-graph-mcp serve --root . --db .sqlite-graph/index.dbEvery command accepts --json; find exits 1 when nothing matches, which makes it usable in
shell conditions.
What it does not do (yet)
Being honest about a heuristic indexer matters more than a longer feature list:
No AST. Imports, exports and declarations are extracted with comment-masked regular expressions, not a TypeScript parser. Multi-line declarations are handled; exotic syntax and computed export names are not.
No cross-file symbol references. There is no
referencesedge yet, sowalkfrom a symbol reaches its file and package, not every call site.No type resolution. Path aliases (
@/…,tsconfigpaths) are not resolved; only relative specifiers and workspace files.Unchanged files are re-parsed. Re-indexing is a full atomic rebuild (fast, but not incremental).
Local scope only.
node_modules,dist,build,.gitand friends are skipped, as are files over 512 KiB and workspaces over 5,000 files (both configurable ingraph_index).
Development
npm install
npm run typecheck # tsc --noEmit, tests included
npm test # builds, then runs unit + stdio MCP integration tests
npm run build # tsc → dist/Layout:
bin/cli.ts CLI entry (shebang, subcommands, JSON output)
src/db.ts schema, FTS5 index, GraphStore (prepared statements)
src/indexer.ts workspace scan, comment masking, symbol/import/heading extraction
src/query.ts find / walk / filter / minus / orphans over SQLite
src/plan.ts pipeline DSL parser + answer executor with citations
src/mcp.ts MCP server and six tools
test/ fixtures, unit tests, stdio MCP protocol testsThe test suite covers indexer counts and idempotency, extension remapping (.js import →
.ts source), cycle-safe traversal, every operator, the plan DSL, orphan detection, the CLI, and
the MCP handshake both through the official SDK client and as raw newline-delimited JSON-RPC.
License
MIT © 2026 Inkwon Jung (@developjik)
Available Tools
6 toolsgraph_filterFilter a node setA
Operator 3 (filter): narrow an explicit node set by kind, path glob/prefix/suffix, name, or tag (tags include code, doc, test, entry, manifest, exported). Combine with graph_find output ids.
Inputs: ids (required), tag, kind, name, +6 more.
graph_findFind nodesB
Operator 1 (find): search files, symbols, markdown headings and packages by text. Uses SQLite FTS5 prefix ranking plus substring fallback, so "index" matches "GraphIndexer".
Inputs: query (required), kind, limit.
graph_indexIndex workspaceA
Scan the workspace for .ts/.tsx/.js/.jsx/.md files and package.json manifests, and build the SQLite graph at .sqlite-graph/index.db (nodes: file, symbol, heading, package; edges: imports, exports, defines, links_to, depends_on). Safe to re-run: it rebuilds atomically.
Inputs: root, force, ignore, maxFiles.
graph_orphansFind orphansB
Operator 4 (minus) applied: files with no inbound imports/links (dead code, stale docs) and symbols that are never exported (dead-code candidates). Test and entry files are excluded unless asked for.
Inputs: limit, includeTests, includeEntries.
graph_planRun a 5-operator planA
Operator 5 (answer): chain find → walk → filter → minus in one call and get structured evidence (nodes, touched edges, path:line citations, per-step trace). Accepts a pipeline string such as find "graph" kind=symbol | walk type=imports depth=2 | filter path=src/** or a JSON {steps:[...]} plan.
Inputs: plan (required), limit.
graph_walkWalk the graphA
Operator 2 (walk): traverse edges from a set of nodes with a recursive CTE (cycle-safe, depth capped). Direction out = dependencies/definitions, in = dependents/references. Each node returns its traversal depth and a path:line citation.
Inputs: start (required), limit, edgeType, maxDepth, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool maps to a distinct operator: index (build), find (text search), filter (narrow node set), walk (traverse edges), orphans (dead-code minus), plan (composed pipeline). The only real overlap is graph_plan versus manually chaining find/walk/filter, and find versus filter could be briefly confused by an agent, but the descriptions clearly delineate text search from explicit-set narrowing.
All six tools use a uniform graph_<verb-or-operator> pattern (graph_index, graph_find, graph_filter, graph_walk, graph_orphans, graph_plan) in consistent snake_case. The naming even encodes the relational-operator metaphor, making the set predictable.
Six tools is a tight, well-scoped surface for a code-graph indexer, with no filler. Each tool corresponds to a genuinely distinct operation (build, search, filter, traverse, dead-code, compose) and the composition tool justifies the small count without bloating it.
The set covers the full query lifecycle: build the graph, search, narrow, traverse dependencies/dependents, detect orphans, and compose multi-step evidence pipelines with citations. Minor gaps exist—no tool to fetch full node details/file contents, no index stats or schema/health inspection, and no incremental update or teardown—but these are workable around a full rebuild.
Maintenance
Related MCP Connectors
Codebase intelligence for AI agents — dead code, blast radius, ownership.
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Deterministic context layer for your codebase: change impact, blast radius, answers with receipts.
Give your AI agent a persistent map of your project's structure, dependencies, and bugs.
Related MCP Servers
- FlicenseNot gradedqualityBmaintenanceProvides graph-native code intelligence for coding agents, enabling them to navigate repositories through compact SQLite-backed symbol graphs and retrieve full source only for relevant symbols.-
- FlicenseNot gradedqualityBmaintenanceEnables AI coding agents to interrogate a local repository deterministically for symbols, dependencies, call paths, routes, tests, and Git impact, returning verified structured evidence with exact line citations instead of requiring the whole codebase to be read.79 PyPI4-
- AlicenseNot gradedqualityNot gradedmaintenanceEnables AI agents to explore a repository by querying a pre-built structural knowledge graph of symbols and their relationships — definitions, callers, callees, blast radius, and file-level impact — instead of grepping and reading files. This cuts the tokens spent on code exploration by roughly 96–99% while running entirely on local SQLite with tree-sitter parsing.MIT
- AlicenseNot gradedqualityAmaintenanceEnables AI coding agents to query a locally indexed structural code graph — source entities, callers/callees, Git relationships and recorded mistakes — so they retrieve focused, token-bounded context instead of reading entire files. It runs over local SQLite and can be served through a CLI, agent hooks, an MCP executable and an authenticated local dashboard.24 npmMIT