Zero-CGO MCP server gives AI agents embedded SQLite knowledge graphs queried via Cypher

A Zero-CGO Model Context Protocol server and standalone CLI tool 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, the project addresses practical tradeoffs in common approaches to AI agent memory.

Vector RAG struggles with deterministic multi-hop queries like "Who is the landlord of the apartment where my son studies?" Dedicated graph databases like Neo4j or Memgraph require a separate server/Docker daemon, 1–2 GB of RAM, network roundtrips, and ongoing operations. Flat markdown or raw SQL files accumulate contradicting notes once multiple agents write to them, and LLMs frequently make mistakes on complex recursive SQL CTEs.

Cypher MCP does instead: a single static binary (~15 MB) with zero-CGO executable and no runtime dependencies — no Docker, Python, or C++ toolchain needed. One local SQLite file using standard ACID SQLite .db file with B-Tree indexes, JSON1, and FTS5, easily shared across different agents and tools. In-process Cypher-to-SQL transpiles Cypher queries to SQLite SQL in-process with typical engine latency under 0.5 ms. Optional evolving schema lets agents define and extend allowed node/edge types without turning the graph into an unstructured dump.

Installation and configuration

brew install vmikhailov/tap/cypher-mcp grabs 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 without Homebrew, macOS Gatekeeper may quarantine the binary. Run xattr -d com.apple.quarantine cypher-mcp-darwin-* and chmod +x cypher-mcp-darwin-*.

Add to 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"]
    }
  }
}

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"]
    }
  }
}

Add to config.yaml:

mcp_servers:
  cypher_graph:
    command: "cypher-mcp"
    args: ["--db", "knowledge_graph.db"]

Ten standard MCP tools via JSON-RPC 2.0 (stdio)

ToolModeDescription
graph_queryRead-onlyTranspiles and executes OpenCypher against SQLite. Returns JSON records with compile and execution timing metrics.
graph_resolve_entityRead-onlyVector semantic entity resolution. Resolves colloquial, inflected, misspelled, or multilingual entity mentions to canonical graph node IDs.
graph_upsert_aliasMutationAssociates an alias or alternative name with a graph node and indexes its embedding vector into SQLite.
graph_searchRead-onlyFull-text search across node IDs and JSON property values. Finds entry-point nodes before path traversals.
graph_batch_upsertMutationAtomically upserts multiple nodes and/or edges in a single ACID transaction with schema validation.
graph_schemaRead-onlySummarizes graph topology: counts of nodes and edges by kind, total graph volume, and active schema rules.
graph_schema_defineDDL / GovernanceDefines or removes allowed node kinds and directed relationships in the taxonomy schema.
graph_set_nodeMutationUpserts a node by unique id, kind, and dynamic JSON properties. Validates against schema if active.
graph_set_edgeMutationUpserts a directed relationship between from_id and to_id with kind and properties. Validates against schema if active.
graph_delete_nodeMutationDeletes a node and cascade-cleans all its incoming and outgoing relationships.

Cypher query capabilities

graph_query supports recursive variable-length pattern matching: -[*1..3]-> (outgoing 1 to 3 hops), <-[*2..5]- (incoming 2 to 5 hops), or-[*]-> (arbitrary depth). A 10-hop default cap means 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 require an explicit LIMIT and depth<=3 to prevent full-graph combinatorial explosion.

Benchmark evaluations

Benchmark / DatasetTask TopologyGraphRAG RecallPlain RAG RecallGraphRAG TokensPlain RAG TokensToken SavingsLatency (Graph vs Plain)
Active Directory Security (BloodHound: 953 nodes, 4.7k ACLs)Privilege escalation, credential dumping, blast radius66.7%33.3%14.0k366.7k26.2x fewer13.1s vs 24.6s
MetaQA Colloquial & Typos1-3 Hops with typos, nicknames, informal titles100.0% (F1: 100%)100.0% (F1: 90.9%)4.2k5.8k1.4x fewer6.3s vs 20.3s (3.2x faster)
MetaQA Standard Multi-Hop1-hop, 2-hop, 3-hop relationship chaining100.0%91.7%1.4k1.1kDirect graph traversals3.1s vs 7.6s (2.4x faster)
GraphRAG vs Plain Vector RAGConversational entity linking and 2-hop dependencies75.0%87.5%21.6k18.3kEntity linking precision18.7s vs 17.9s
Enterprise AuditTransitive blast radius, unpatched DBs, orphaned services93.8%0.0% (timeouts)26.9k39.8k1.5x fewer19.8s vs 29.2s (timeout)
2WikiMultihopQAMulti-hop reasoning across distractor documents100.0%100.0%4.2k1.5kStructural fact linking6.1s vs 3.2s
Zero-Shortcut Depth ScalingScaling search depth where intermediate nodes lack shortcuts100.0%75.0% (0% at 4-hop)6.6k4.6kExhaustive traversal12.6s vs 15.5s (1.6x faster at 4-hop)
Architecture Agent EvalsDiagnostic multi-hop failure analysis and cascade impact100.0%100.0%4.2k2.7kSingle query paths3.8s vs 12.5s (3.3x faster)
Engine Micro-BenchmarksPoint lookups, 2-hop joins, recursive traversal, FTS5100.0%75.0%~110 / q~1,800 / q16.4x fewer<0.5 ms vs ~250 ms

CLI commands

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.

CommandAliasDescriptionExample
queryqRun OpenCypher queries against the SQLite graphcypher-mcp query "MATCH (n) RETURN n LIMIT 5"
searchsFull-text FTS5 search across nodes and propertiescypher-mcp search "database"
resolverSemantic vector entity resolution / linkingcypher-mcp resolve "alice"
node-Inspect, create, update, or delete nodescypher-mcp node get alice
edge-Create or update directed relationshipscypher-mcp edge set alice proj1 CONTRIBUTES
schema-View topology volume and enforce schema rulescypher-mcp schema show
alias-Register semantic aliases for entity linkingcypher-mcp alias upsert alice "Al"
batch-Import batches of nodes and edges atomicallycypher-mcp batch import graph.json
serve-Explicitly run as an MCP servercypher-mcp serve --db graph.db
version-Print version and architecture infocypher-mcp version

Query output format

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

Node and edge operations

# 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 management

# 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"

Import graph data atomically

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

Automatic schema initialization

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);

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 sets user_version = 1. Idempotency: subsequent boots skip migration passes, eliminating startup latency. Corrupt FTS Recovery: if SQLite reports no such table: nodes_fts or virtual table corruption, the migration routine automatically drops and rebuilds the FTS index safely from active node records.

SQLite backup and restore

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

The script connects via read-only URI mode (?mode=ro), utilizes the SQLite Online Backup API (sqlite3_backup), executes PRAGMA integrity_check and PRAGMA foreign_key_check on the completed snapshot, and performs an atomic os.link publication to prevent partial writes.

To roll back or restore from a backup: terminate any running cypher-mcp or 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 -wal or -shm files: 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.

Secure API credential handling

External vector embedding requests (Google Gemini) pass API tokens strictly through the x-goog-api-key HTTP 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 match or where inside 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: go test -v ./...

MIT License. Copyright (c) 2026 Viacheslav Mikhailov.