Skip to main content
Glama
sqlite-graph-mcp

sqlite-graph-mcp

by developjik

sqlite-graph-mcp

CI

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:1

Most "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 via better-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 sqlite3 and check the agent's reasoning yourself.

  • Citations by construction. Nodes carry path and line; 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

file

.ts .tsx .js .jsx .mts .cts .mjs .cjs .md .mdx .markdown package.json

file:src/index.ts

symbol

top-level function / class / `const

let

heading

Markdown # headings, GitHub-style slugs

heading:docs/spec.md#usage

package

package.json name + dependencies, plus bare imports

package:left-pad

Edge type

Meaning

imports

file → file (static import, export … from, require, dynamic import())

exports

file → symbol (declaration is exported)

defines

file → symbol, file → heading, package.json → its package

links_to

Markdown link/reference → file or heading, including #anchors

depends_on

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-mcp

MCP 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/repo

Cursor (~/.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

find

graph_find

"Where is walkGraph defined?"

walk

graph_walk

"What does this file import, transitively?"

filter

graph_filter

"Of these nodes, which are docs under docs/?"

minus

graph_orphans (set difference)

"Which files are never imported or linked?"

answer

graph_plan

"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=file

The 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

find <query>

kind=file,symbol, limit=20; * lists all, *.ts is a glob

walk

type=imports,links_to, `dir=out

filter

kind=, notKind=, path=src/**, prefix=, suffix=, name=, regex=, tag=, limit=

minus find <query>

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.db

Every 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 references edge yet, so walk from a symbol reaches its file and package, not every call site.

  • No type resolution. Path aliases (@/…, tsconfig paths) 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, .git and friends are skipped, as are files over 512 KiB and workspaces over 5,000 files (both configurable in graph_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 tests

The 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 tools
graph_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

    A3.8/5.0

    Scored across 6 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      B
      maintenance
      Provides 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.
      -
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 PyPI
      4
      -
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables 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 npm
      MIT