Kuzu Knowledge Graph MCP Server

A beginner-friendly Model Context Protocol server that connects to an embedded Kuzu graph database and lets AI clients read a knowledge graph.

This project is designed for a first Kuzu journey:

1. Create a small knowledge graph.
2. Store it in Kuzu.
3. Expose read-only graph tools through MCP.
4. Connect the MCP server to an AI client.
5. Ask graph-backed questions.

What You Get

• TypeScript MCP server over stdio
• Embedded Kuzu database connection
• Auto-created graph schema
• Optional sample data seed
• Read-only Cypher guard
• Six MCP tools
• One schema resource
• Dockerfile
• Step-by-step docs

Why Kuzu

Kuzu is an embedded property graph database. It runs inside your application process, stores graph data on disk, and supports Cypher queries. That makes it a good fit for local or product-embedded knowledge graph workloads where you do not want to run a separate graph database server.

Architecture

AI Client
  |
  | MCP stdio
  v
Kuzu Knowledge Graph MCP Server
  |
  | Kuzu Node.js API
  v
Embedded Kuzu DB directory

Requirements

• Node.js 20 or newer
• npm, pnpm, or another Node package manager
• macOS, Linux, or Windows with a supported Kuzu Node package

Quick Start

git clone <your-repo-url>
cd kuzu-knowledge-graph-mcp

npm install
npm run build
npm run seed
npm run smoke

Expected smoke result:

{
  "status": "ok",
  "nodeCounts": {
    "Document": 4,
    "Chunk": 8,
    "Entity": 8,
    "Topic": 4
  }
}

Run The MCP Server

Development:

npm run dev

Production-style:

npm run build
npm run start

The server uses stdio, so it will appear to wait silently. That is normal. MCP clients talk to it through stdin/stdout.

Environment Variables

Copy the example file:

cp .env.example .env

Important settings:

Variable	Default	Meaning
KUZU_DB_PATH	./data/kuzu-demo	Directory where Kuzu stores the database
KUZU_AUTO_CREATE_SCHEMA	true	Create node and relationship tables on startup
KUZU_AUTO_SEED	true	Seed sample data when the database has no documents
MCP_SERVER_NAME	kuzu-knowledge-graph	Name shown to MCP clients

Connect To Claude Desktop Or Another MCP Client

Build first:

npm run build

Then add a config like this to your MCP client. Replace the paths with your real absolute path.

{
  "mcpServers": {
    "kuzu-knowledge-graph": {
      "command": "node",
      "args": ["/absolute/path/to/kuzu-knowledge-graph-mcp/dist/src/index.js"],
      "env": {
        "KUZU_DB_PATH": "/absolute/path/to/kuzu-knowledge-graph-mcp/data/kuzu-demo",
        "KUZU_AUTO_CREATE_SCHEMA": "true",
        "KUZU_AUTO_SEED": "true"
      }
    }
  }
}

An editable copy is available in mcp-config.example.json.

Available MCP Tools

• kg_overview: graph counts, topics, and examples
• kg_search: keyword search across documents, chunks, entities, and topics
• kg_get_document_context: document, chunks, topics, and entities
• kg_entity_neighborhood: one-hop entity relationships and supporting chunks
• kg_question_context: compact graph-backed evidence pack for a natural-language question
• kg_readonly_cypher: guarded read-only Cypher query

Full tool guide: docs/TOOLS.md

Create And Run A Simple MCP Client

This repo includes a beginner MCP client that starts the Kuzu MCP server, lists tools, reads the schema resource, and calls graph tools.

npm run client:demo

Client guide: docs/CLIENT.md

Example Journey

The included sample graph models a GenAI Workbench support and deployment knowledge graph.

Try asking your MCP client:

Use the Kuzu knowledge graph. How does the context graph reduce AI cost and how do I deploy it safely?

The expected journey:

1. Search chunks for context graph, cost, deployment, and safety.
2. Expand to documents such as doc-context-cost and doc-deployment.
3. Pull entities like Kuzu, Context Graph, API Key, Tenant Isolation, and REST API.
4. Return a small evidence pack for the LLM.

Detailed walkthrough: docs/DATA_JOURNEY.md

Useful Read-Only Cypher

MATCH (d:Document)-[:HAS_CHUNK]->(c:Chunk)
RETURN d.title AS document, c.section AS section, c.text AS text
LIMIT 5

MATCH (a:Entity)-[r:RELATED_TO]->(b:Entity)
RETURN a.name AS fromEntity, r.relation AS relation, b.name AS toEntity
LIMIT 10

More examples: examples/graph-journey.cypher

Deployment

See docs/DEPLOYMENT.md.

Project Structure

src/
  index.ts                 MCP server entrypoint
  kuzuGraph.ts             Kuzu connection and query wrapper
  knowledgeGraphService.ts Graph read operations
  schema.ts                Kuzu graph schema
  seedData.ts              Sample data journey
  cypher.ts                Read-only Cypher validation
scripts/
  seed.ts                  Reset and seed the demo graph
  smoke.ts                 Build confidence test
docs/
  DATA_JOURNEY.md
  DEPLOYMENT.md
  TOOLS.md
examples/
  graph-journey.cypher
  questions.md

Notes For Beginners

• Kuzu is embedded. You are not connecting to a database server URL. You are opening a database directory.
• MCP stdio servers do not expose an HTTP port. Your AI client starts the server command and talks through standard input/output.
• Do not write normal logs to stdout in an MCP server. stdout is reserved for protocol messages.
• Keep raw Cypher read-only unless you are building an admin-only server.

References

• Kuzu documentation: https://kuzudb.github.io/docs/
• Kuzu Node.js API: https://kuzudb.github.io/docs/client-apis/nodejs/
• MCP TypeScript SDK: https://github.com/modelcontextprotocol/typescript-sdk