Kuzu Knowledge Graph 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
• Built-in Kuzu Graph Console web app
• In-app Learn & Practice tutorial center
• 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

Browser
  |
  | HTTP JSON + static UI
  v
Kuzu Graph Console App
  |
  | 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",
  "tutorialCount": 5,
  "tutorialPracticeRows": 1,
  "nodeCounts": {
    "Document": 4,
    "Chunk": 8,
    "Entity": 8,
    "Topic": 4
  }
}

Run Kuzu Graph Console

Kuzu Graph Console is the built-in browser app for opening the configured Kuzu database, inspecting schema, learning with tutorials, running read-only Cypher, exploring graph results, importing source text, and reviewing logs.

npm run app:dev

Open:

http://127.0.0.1:8787

Default local login:

[email protected] / kuzu

Beginner user guide: docs/USER_GUIDE.md

Learn & Practice guide: docs/LEARN_AND_PRACTICE.md

Console API/reference guide: docs/STUDIO.md

To create a new graph from a local file, pasted documents, or notes, follow Create A New Knowledge Graph.

To learn Kuzu concepts safely before using your own data, open Learn & Practice and load a tutorial dataset into .kuzu-practice/<tutorial-id>/.

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
  tutorialService.ts       Learn & Practice sandbox service
  tutorials.ts             Bundled tutorial registry and sample datasets
  appServer.ts              Kuzu Graph Console HTTP API and static server
  schema.ts                Kuzu graph schema
  seedData.ts              Sample data journey
  cypher.ts                Read-only Cypher validation
web/
  index.html
  styles.css
  app.js
scripts/
  seed.ts                  Reset and seed the demo graph
  smoke.ts                 Build confidence test
docs/
  USER_GUIDE.md
  CONSOLE_ARCHITECTURE.md
  DATA_JOURNEY.md
  DEPLOYMENT.md
  LEARN_AND_PRACTICE.md
  STUDIO.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