A Zero-CGO Model Context Protocol (MCP) server and standalone CLI tool that gives AI agents and developers an embedded SQLite knowledge graph queried via Cypher — no separate database server required.
Powered by cypher-sql-go and pure-Go SQLite (modernc.org/sqlite).
Why Cypher MCP?
Common approaches to AI agent memory each have practical tradeoffs:
- Vector RAG: Struggles with deterministic multi-hop queries ("Who is the landlord of the apartment where my son studies?").
- Dedicated Graph Databases (Neo4j, Memgraph): Require a separate server/Docker daemon, 1–2 GB of RAM, network roundtrips, and ongoing ops.
- Flat Markdown / Raw SQL: Markdown files accumulate contradicting notes once multiple agents write to them, and LLMs frequently make mistakes on complex recursive SQL CTEs.
What Cypher MCP does instead:
- Single Static Binary (~15 MB): Zero-CGO executable with no runtime dependencies — no Docker, Python, or C++ toolchain.
- One Local SQLite File: Standard ACID SQLite
.dbfile using B-Tree indexes, JSON1, and FTS5, easily shared across different agents and tools. - In-Process Cypher-to-SQL: Transpiles Cypher queries (
MATCH (p:Person)-[:OWES]->(o) RETURN o) to SQLite SQL in-process (< 0.5 ms typical engine latency). - Optional Evolving Schema: Agents can define and extend allowed node/edge types without turning the graph into an unstructured dump.
Scaling Beyond Local Storage
If you need a shared multi-tenant graph across a team, cypher-sql-go can target a centralized backend (such as PostgreSQL with pgvector).
Quick Start
1. Install
Via Homebrew (macOS & Linux — Recommended)
brew install vmikhailov/tap/cypher-mcp
Download Prebuilt Binary
Grab the latest static binary for your OS and architecture from Releases:
- Linux (
x86_64,arm64) - macOS (
Apple Silicon arm64,Intel amd64) - Windows (
x86_64)
Note for macOS direct downloads: If downloaded directly without Homebrew, macOS Gatekeeper may quarantine the binary. Run
xattr -d com.apple.quarantine cypher-mcp-darwin-*andchmod +x cypher-mcp-darwin-*.
2. Configure Your AI Agent
Claude Desktop
Add to your claude_desktop_config.json:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"knowledge_graph": {
"command": "/usr/local/bin/cypher-mcp",
"args": ["--db", "/path/to/my_knowledge_graph.db"]
}
}
}Antigravity IDE / Cursor / VS Code
Add to mcp_config.json (or .cursor/mcp.json):
{
"mcpServers": {
"cypher_graph": {
"command": "C:/Tools/cypher-mcp.exe",
"args": ["--db", "C:/Data/knowledge_graph.db"]
}
}
}Hermes Agent
Add to config.yaml:
mcp_servers: cypher_graph: command: "cypher-mcp" args: ["--db", "knowledge_graph.db"]
MCP Tools
cypher-mcp exposes 10 standard MCP tools via JSON-RPC 2.0 (stdio):
| Tool | Mode | Description |
|---|---|---|
graph_query |
Read-only | Transpiles and executes OpenCypher against SQLite. Returns JSON records with compile and execution timing metrics. |
graph_resolve_entity |
Read-only | Vector semantic entity resolution (Entity Linking). Resolves colloquial, inflected, misspelled, or multilingual entity mentions (e.g. "k8s", "Beemer", "Al") to canonical graph node IDs. |
graph_upsert_alias |
Mutation | Associates an alias or alternative name with a graph node and indexes its embedding vector into SQLite. |
graph_search |
Read-only | Full-text search (SQLite FTS5) across node IDs and JSON property values. Finds entry-point nodes before path traversals. |
graph_batch_upsert |
Mutation | Atomically upserts multiple nodes and/or edges in a single ACID transaction with schema validation. |
graph_schema |
Read-only | Summarizes graph topology: counts of nodes and edges by kind, total graph volume, and active schema rules. |
graph_schema_define |
DDL / Governance | Defines or removes allowed node kinds and directed relationships in the taxonomy schema. |
graph_set_node |
Mutation | Upserts a node by unique id, kind, and dynamic JSON properties. Validates against schema if active. |
graph_set_edge |
Mutation | Upserts a directed relationship between from_id and to_id with kind and properties. Validates against schema if active. |
graph_delete_node |
Mutation | Deletes a node and cascade-cleans all its incoming and outgoing relationships. |
Variable-Length Path Traversal
graph_query supports recursive variable-length pattern matching:
- Syntax:
-[*1..3]->(outgoing 1 to 3 hops),<-[*2..5]-(incoming 2 to 5 hops), or-[*]->(arbitrary depth). - 10-Hop Default Cap: Unbounded patterns like
-[*]->and-[*1..]->automatically default to a maximum depth of 10 hops (min=1, max=10) to prevent runaway queries. - Safety Guardrails: All queries time out after 15 seconds. Always anchor at least one endpoint (e.g.
(p:Person {name: 'Alice'})-[*1..3]->(target)); fully unanchored traversals (MATCH (x)-[*1..2]->(y)) strictly require an explicitLIMIT(and depth<= 3) to prevent full-graph combinatorial explosion.
Benchmarks
Architecture Comparison
| Aspect | Cypher MCP (Embedded) | Text-to-SQL (Relational) | Vector RAG (Top-K Chunks) | Neo4j (Docker JVM) |
|---|---|---|---|---|
| Multi-Hop Queries | Deterministic Cypher-to-SQL | Manual recursive CTEs | Top-K chunk retrieval | Deterministic Cypher |
| Query Latency | < 0.5 ms (in-process) | < 1 ms (in-process) | ~100–300 ms (embed + search) | 15–45 ms (Bolt TCP) |
| Memory Footprint | ~15 MB RAM | ~15 MB RAM | 200 MB – 1 GB | 1.2 – 2.5 GB RAM |
| Infrastructure | Single static binary + .db file |
App-managed SQL schema | Embedding model + vector store | Docker daemon + JVM |
Empirical Agent Benchmarks
Evaluations run with Gemini 3.8 Flash across multi-hop datasets:
| Benchmark / Dataset | Task Topology | GraphRAG Recall | Plain RAG Recall | GraphRAG Tokens | Plain RAG Tokens | Token Savings | Latency (Graph vs Plain) |
|---|---|---|---|---|---|---|---|
| Active Directory Security (BloodHound: 953 nodes, 4.7k ACLs) |
Privilege escalation, credential dumping, blast radius | 66.7% | 33.3% | 14.0k | 366.7k | 26.2x fewer | 13.1s vs 24.6s |
| MetaQA Colloquial & Typos (134,741 facts, 43k nodes) |
1-3 Hops with typos, nicknames, informal titles | 100.0% (F1: 100%) | 100.0% (F1: 90.9%) | 4.2k | 5.8k | 1.4x fewer | 6.3s vs 20.3s (3.2x faster) |
| MetaQA Standard Multi-Hop (134,741 facts, 43k nodes) |
1-hop, 2-hop, 3-hop relationship chaining | 100.0% | 91.7% | 1.4k | 1.1k | Direct graph traversals | 3.1s vs 7.6s (2.4x faster) |
| GraphRAG vs Plain Vector RAG (Synthetic corporate topology) |
Conversational entity linking and 2-hop dependencies | 75.0% | 87.5% | 21.6k | 18.3k | Entity linking precision | 18.7s vs 17.9s |
| Enterprise Audit (250 corporate docs, 230 services) |
Transitive blast radius, unpatched DBs, orphaned services | 93.8% | 0.0% (timeouts) | 26.9k | 39.8k | 1.5x fewer | 19.8s vs 29.2s (timeout) |
| 2WikiMultihopQA (Academic benchmark w/ distractors) |
Multi-hop reasoning across distractor documents | 100.0% | 100.0% | 4.2k | 1.5k | Structural fact linking | 6.1s vs 3.2s |
| Zero-Shortcut Depth Scaling (Branching tree, 1 to 4 hops) |
Scaling search depth where intermediate nodes lack shortcuts | 100.0% | 75.0% (0% at 4-hop) | 6.6k | 4.6k | Exhaustive traversal | 12.6s vs 15.5s (1.6x faster at 4-hop) |
| Architecture Agent Evals (Distributed microservice graph) |
Diagnostic multi-hop failure analysis and cascade impact | 100.0% | 100.0% | 4.2k | 2.7k | Single query paths | 3.8s vs 12.5s (3.3x faster) |
| Engine Micro-Benchmarks (Go / SQLite in-process B-Tree) |
Point lookups, 2-hop joins, recursive traversal, FTS5 | 100.0% | 75.0% | ~110 / q | ~1,800 / q | 16.4x fewer | <0.5 ms vs ~250 ms |
Command-Line Interface (CLI)
cypher-mcp is a dual-mode executable. When invoked without arguments (or with --db/--log on a pipe), it operates as a standard JSON-RPC 2.0 MCP server over stdio. When invoked with any CLI subcommand, it acts as a terminal CLI tool for developers, scripts, and shell pipelines.
Subcommands Overview
| Command | Alias | Description | Example |
|---|---|---|---|
query |
q |
Run OpenCypher queries against the SQLite graph | cypher-mcp query "MATCH (n) RETURN n LIMIT 5" |
search |
s |
Full-text FTS5 search across nodes and properties | cypher-mcp search "database" |
resolve |
r |
Semantic vector entity resolution / linking | cypher-mcp resolve "alice" |
node |
- | Inspect, create, update, or delete nodes | cypher-mcp node get alice |
edge |
- | Create or update directed relationships | cypher-mcp edge set alice proj1 CONTRIBUTES |
schema |
- | View topology volume and enforce schema rules | cypher-mcp schema show |
alias |
- | Register semantic aliases for entity linking | cypher-mcp alias upsert alice "Al" |
batch |
- | Import batches of nodes and edges atomically | cypher-mcp batch import graph.json |
serve |
- | Explicitly run as an MCP server | cypher-mcp serve --db graph.db |
version |
- | Print version and architecture info | cypher-mcp version |
Querying the Graph
By default, queries render formatted ASCII tables on interactive terminals and JSON when piped into another program or when --format json is passed:
# Pretty-printed table output cypher-mcp query "MATCH (p:Person)-[:WORKS_ON]->(prj) RETURN p.name, prj.name" # Parameterized query with JSON output cypher-mcp query --params '{"minAge": 21}' --format json \ "MATCH (p:Person) WHERE p.age >= $minAge RETURN p.name, p.age" # Pipe Cypher queries via stdin echo "MATCH (n) RETURN count(n) AS total_nodes" | cypher-mcp query -
Full-Text Search & Entity Resolution
# Full-text search across IDs and all JSON property attributes cypher-mcp search "kubernetes" --limit 10 # Semantic vector entity linking (uses GEMINI_API_KEY when configured) cypher-mcp resolve "k8s cluster" --top-k 3
Direct Node and Edge Manipulation
# Create or update a node (kind, properties) cypher-mcp node set alice Person '{"name":"Alice","role":"Architect"}' # Read node cypher-mcp node get alice # Create a directed relationship cypher-mcp edge set alice proj1 CONTRIBUTES '{"since": 2024}' # Delete node and cascade-clean its relationships cypher-mcp node delete alice
Schema Governance
# Display node/edge volumes, distinct kinds, and enforcement status cypher-mcp schema show # Define strict taxonomy rules (whitelist allowed node kinds and relations) cypher-mcp schema define \ --node-kinds "Person,Project,Document" \ --relations "CONTRIBUTES:Person:Project,REFERENCES:Document:Project"
Batch Ingestion
Import graph data atomically in a single ACID transaction from a file or stdin:
cat << 'EOF' | cypher-mcp batch import - { "nodes": [ {"id": "bob", "kind": "Person", "properties": {"name": "Bob"}}, {"id": "api", "kind": "Service", "properties": {"tier": "backend"}} ], "edges": [ {"from_id": "bob", "to_id": "api", "kind": "MAINTAINS"} ] } EOF
Relational Schema
cypher-mcp automatically initializes the following universal graph schema if the database does not exist:
CREATE TABLE nodes ( id TEXT PRIMARY KEY, kind TEXT NOT NULL, properties TEXT NOT NULL ); CREATE TABLE edges ( from_id TEXT NOT NULL, to_id TEXT NOT NULL, kind TEXT NOT NULL, properties TEXT NOT NULL ); CREATE INDEX idx_edges_from ON edges(from_id); CREATE INDEX idx_edges_to ON edges(to_id); CREATE INDEX idx_edges_kind ON edges(kind); CREATE INDEX idx_nodes_kind ON nodes(kind);
Operational Safety, Migrations & Backups
Versioned Schema Migrations (PRAGMA user_version = 1)
cypher-mcp automatically tracks schema versioning via SQLite's native PRAGMA user_version:
- V1 Auto-Migration: On startup, the server inspects
PRAGMA user_version. If legacy (user_version = 0), it automatically dedupes duplicate edges, creates unique indexes (idx_edges_unique,idx_aliases_unique), initializes the FTS5 search index (nodes_fts), and setsuser_version = 1. - Idempotency: Subsequent boots skip migration passes, eliminating startup latency.
- Corrupt FTS Recovery: If SQLite reports
no such table: nodes_ftsor virtual table corruption, the migration routine automatically drops and rebuilds the FTS index safely from active node records.
Live WAL Hot Backups
SQLite databases in WAL mode cannot be safely backed up by copying the .db file alone (as uncommitted transactions and checkpoints reside in -wal and -shm sidecars).
Use the included backup script to take atomic, consistent snapshots without pausing the server:
# Consistent snapshot of a live database
python scripts/backup_sqlite.py data/knowledge_graph.db backups/backup_20261004.dbThe script:
- Connects via read-only URI mode (
?mode=ro). - Utilizes the SQLite Online Backup API (
sqlite3_backup). - Executes
PRAGMA integrity_checkandPRAGMA foreign_key_checkon the completed snapshot. - Performs an atomic
os.linkpublication to prevent partial writes.
Rollback & Disaster Recovery
To roll back or restore from a backup:
- Terminate any running
cypher-mcpor agent processes pointing to the target database. - Verify the snapshot using
python scripts/backup_sqlite.py <backup.db> <restored_test.db>. - Atomically replace the database file and remove any stale
-walor-shmfiles:rm -f knowledge_graph.db-wal knowledge_graph.db-shm mv backups/snapshot.db knowledge_graph.db
- Start
cypher-mcp. The migration subsystem will verify integrity and schema on boot.
Security Invariants
- Secure API Credential Handling: External vector embedding requests (Google Gemini) pass API tokens strictly through the
x-goog-api-keyHTTP request header, never in query string parameters or logs. Outbound error messages are sanitized to strip any tokens before returning to MCP clients. - Connection Pool Isolation: Writer (
MaxOpenConns = 1) and reader pools are configured with immutable DSN PRAGMAs (foreign_keys(1),journal_mode(WAL),busy_timeout(5000)), preventing database locks or unconstrained concurrent writes. - JSON-RPC 2.0 Conformance: Fully respects JSON-RPC 2.0 specifications. Notifications are processed silently, and 64-bit integer IDs (
json.RawMessage) preserve full integer precision without truncation. - Token-Safe Identifier Validation: Cypher queries strip string literals before validating identifiers, preventing false rejections of valid queries containing words like
matchorwhereinside string values.
Building from Source
Requires Go 1.22+:
git clone https://github.com/vmikhailov/cypher-mcp.git cd cypher-mcp go build -ldflags="-s -w" -o bin/cypher-mcp ./cmd/cypher-mcp
To run tests:
License
MIT License. Copyright (c) 2026 Viacheslav Mikhailov.