neo4j-mcp-workspace-template

A template for end-to-end Neo4j graph development using MCP servers. Compatible with Claude Code, Cursor, Gemini CLI, GitHub Copilot (VS Code), OpenCode, OpenAI Codex CLI, and Mistral Vibe.

Quick Start

git clone https://github.com/neo4j-field/neo4j-mcp-workspace-template
cd neo4j-mcp-workspace-template
chmod +x setup.sh && ./setup.sh

Then open your AI coding tool:

setup.sh will:

1. Prompt for your Neo4j credentials and OpenAI API key
2. Write .env with your configuration
3. Install dependencies for the local MCP servers
4. Generate MCP config files for all 7 tools:
   • .mcp.json — Claude Code
   • .cursor/mcp.json — Cursor
   • .gemini/settings.json — Gemini CLI
   • .vscode/mcp.json — GitHub Copilot (VS Code)
   • opencode.json — OpenCode
   • .codex/config.toml — OpenAI Codex CLI
   • .vibe/config.toml — Mistral Vibe

---

Claude Desktop

If you use Claude Desktop (not one of the 7 coding tools above), install the workspace as a Desktop Extension — no git clone needed.

Prerequisites

1. uv — must be installed before the extension can start (see Installing uv below)

2. Two Neo4j databases — the workspace uses a Documents DB (chunks, entities) and an Ontology DB (extraction schema). Two options:

   Option	How
   Two Aura instances	Create two free AuraDB instances — one for documents, one for the ontology. Each has its own URI, username, and password.
   Neo4j Desktop (local)	Install Neo4j Desktop, create one DBMS, then add two databases inside it (e.g. neo4j and ontology). Both share the same URI and credentials.

   Aura free tier note: each Aura instance has a single database named neo4j — you cannot create additional databases. Use two separate instances.

3. An OpenAI API key — for embeddings and entity extraction (or configure another provider via Extra Environment Variables in the install dialog)

Install

1. Download neo4j-mcp-workspace.dxt from the latest release
2. Double-click the .dxt file — Claude Desktop opens an install dialog
3. Fill in your credentials:
   • Documents DB — URI, username, password, database name (e.g. neo4j)
   • Ontology DB — URI, username, password, database name (e.g. neo4j on Aura, ontology on Desktop). Leave URI/username/password blank if using the same Neo4j instance as Documents DB.
   • OpenAI API key — for embeddings; also used for extraction if your extraction model is OpenAI
   • Extraction model — defaults to openai/gpt-5.4-mini; change to any LiteLLM-compatible model
4. Click Install — all MCP servers start automatically

What makes it different

The workspace stores your extraction ontology as a graph in your Ontology DB. Open it in Neo4j Bloom to visualize and edit it directly — add aliases, adjust blocklists, define new entity types — then ask Claude to re-extract. Changes are live immediately. No files, no code.

A companion SME skill (build-ontology-driven-graph) walks non-developers through the full flow — install it via drag-drop from the latest skill release. See Install the SME skill in the Claude Desktop Guide.

→ See the Claude Desktop Guide for the full workflow, Bloom editing, and troubleshooting.

Providing files to the workspace

The MCP servers run on your local machine and access your local filesystem. When Claude asks you for a PDF or CSV file, provide the full path on your computer (e.g. /Users/alice/Documents/report.pdf on Mac, C:\Users\alice\Documents\report.pdf on Windows).

Do not use the Claude Desktop file upload button — uploaded files go to a sandbox the MCP servers cannot reach. Save the file to your disk and give Claude the path instead.

---

Requirements

• uv — required to run all MCP servers (provides uvx)
• Neo4j 2025.01+ — required for native VECTOR type used by lexical-graph
  • Neo4j Desktop or AuraDB
• LLM provider — for embedding generation and entity extraction (see LLM Configuration below)
• Google MCP Toolbox (optional) — only if using BigQuery as a data source

Installing uv

uv is a fast Python package manager that also provides uvx — used to run the MCP servers without a manual Python setup. Install it once on your machine:

macOS / Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Then restart your terminal (or run source $HOME/.local/bin/env).

Windows (PowerShell)

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Then restart your terminal.

Verify the install

uv --version   # should print e.g. uv 0.6.x
uvx --version  # same binary, should also work

Note for Claude Desktop users: uv must be installed and on your PATH before the Neo4j workspace extension can start. Claude Desktop does not bundle uv.

Full docs: docs.astral.sh/uv/getting-started/installation

---

MCP Servers

This workspace configures five MCP servers:

Data Modeling

Designs and validates graph schemas from sample data. Provides example data models and Mermaid visualizations.

• Server: mcp-neo4j-data-modeling (remote via uvx)
• Required credentials: none

Ingest

Loads structured CSV data into Neo4j using parameterized Cypher queries generated by the Data Modeling server.

• Server: mcp-neo4j-ingest (local — mcp-neo4j-ingest/)
• Required credentials: Neo4j connection vars

Lexical Graph

Parses PDFs into a searchable graph with Document, Chunk, and optional Image/Table/Section/Page nodes, vector embeddings, and fulltext indexes. Supports 4 parse modes:

• pymupdf — fast text extraction + optional image/table capture (default)
• docling — full layout detection with sections, tables, captions
• page_image — vision model per page (slides, diagrams, visual-heavy docs)
• vlm_blocks — pymupdf + VLM block classification (faster than docling, experimental)

Tools must be called in a specific order depending on the parse mode. See mcp-neo4j-lexical-graph/README.md for the full workflow table.

• Server: mcp-neo4j-lexical-graph (local — mcp-neo4j-lexical-graph/)
• Required credentials: Neo4j connection vars + LLM API key + EMBEDDING_MODEL

Entity Graph

Extracts structured entities from lexical graph chunks using an LLM. Supports 100+ providers via LiteLLM. Processing runs asynchronously in the background.

• Server: mcp-neo4j-entity-graph (local — mcp-neo4j-entity-graph/)
• Required credentials: Neo4j connection vars + LLM API key + EXTRACTION_MODEL

GraphRAG

Read/write Cypher queries, vector search, fulltext search, and graph-traversal queries. Replaces the standalone Cypher server and adds RAG retrieval on top.

• Server: mcp-neo4j-graphrag (local — cloned by setup.sh)
• Key tools: read_neo4j_cypher, write_neo4j_cypher, get_neo4j_schema_and_indexes, vector_search, fulltext_search, search_cypher_query, read_node_image
• Required credentials: reads from .env via python-dotenv

BigQuery (optional)

Connects to BigQuery as a source database. Requires the Google MCP Toolbox CLI.

brew install mcp-toolbox

---

Workflow

Structured data (CSV)

1. Discovery — analyze CSV samples; identify entities, relationships, and use cases
2. Model — design a graph data model with the Data Modeling server
3. Ingest — load CSV data into Neo4j with the Ingest server
4. Query — generate Cypher for each use case
5. Validate — run queries and verify results address the use cases

Unstructured data (PDF) — use /develop-neo4j-graph

1. Discovery — review PDFs; select parse mode based on document type
2. Use case — infer CHATBOT or ANALYTICAL mode from use case description
3. Model — design a graph data model with the Data Modeling server
4. Lexical Graph — parse PDFs, chunk (if needed), generate descriptions (if images/tables), embed
5. Schema + validators — export extraction schema and review Pydantic validators
6. Entity Graph — extract structured entities from chunks
7. Q&A / Analysis — answer questions (CHATBOT) or generate Cypher reports (ANALYTICAL)
8. Report — save results to outputs/reports/

Use the develop-neo4j-graph skill for the full guided workflow (CSV + PDF, CHATBOT or ANALYTICAL mode):

---

LLM Configuration

Both EMBEDDING_MODEL and EXTRACTION_MODEL accept any LiteLLM-compatible model string. The defaults use OpenAI, but you can swap to any provider — including local models via Ollama — by editing two lines in .env.

Default (OpenAI)

EMBEDDING_MODEL=text-embedding-3-small
EXTRACTION_MODEL=gpt-5.4-mini

Fast, high quality, requires an OpenAI API key.

Local models via Ollama

Run models entirely on your own hardware — no API key needed. Install Ollama, pull the models, then update .env:

EMBEDDING_MODEL=ollama/nomic-embed-text
EXTRACTION_MODEL=ollama/qwen3:8b

ollama pull nomic-embed-text
ollama pull qwen3:8b

Recommended local models:

Tradeoffs vs cloud models: Local extraction is slower due to sequential processing (expect 15–45 min per 100 chunks vs ~2 min with gpt-5.4-mini). Quality-wise, qwen3:8b matches cloud models for simple entity extraction, but phi4-mini misses relationships.

Other providers

setup.sh only prompts for OPENAI_API_KEY. For other providers, run setup.sh first, then add the provider’s credentials to .env manually:

# Mistral
MISTRAL_API_KEY=...
EMBEDDING_MODEL=mistral/mistral-embed
EXTRACTION_MODEL=mistral/mistral-small-latest

# Anthropic
ANTHROPIC_API_KEY=sk-ant-...
EXTRACTION_MODEL=anthropic/claude-haiku-4-5-20251001

# Azure OpenAI
AZURE_API_KEY=...
AZURE_API_BASE=https://YOUR_RESOURCE.openai.azure.com
AZURE_API_VERSION=2024-02-01
EXTRACTION_MODEL=azure/gpt-4o-mini

# AWS Bedrock
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AWS_REGION_NAME=us-east-1
EXTRACTION_MODEL=bedrock/anthropic.claude-3-haiku-20240307-v1:0

# Google Gemini
GEMINI_API_KEY=...
EXTRACTION_MODEL=gemini/gemini-2.0-flash

# Ollama (local, no key needed — see section above)
EXTRACTION_MODEL=ollama/qwen3:8b

Full provider list: docs.litellm.ai/docs/providers

---

Setup

Primary: ./setup.sh

chmod +x setup.sh && ./setup.sh

The script is idempotent. Re-run it any time to:

• Regenerate all 7 MCP config files after credential changes
• Re-install server dependencies after a git pull

Alternative: Manual Setup

Manual setup steps

1. Create .env

Copy .env.example to .env and fill in your values:

cp .env.example .env
# Edit .env with your Neo4j credentials and API keys

2. Clone the graphrag server

git clone --depth 1 https://github.com/neo4j-field/mcp-neo4j-graphrag

3. Install local server dependencies

uv sync --directory mcp-neo4j-ingest
uv sync --directory mcp-neo4j-lexical-graph
uv sync --directory mcp-neo4j-entity-graph
uv sync --directory mcp-neo4j-graphrag

4. Generate MCP config files

Use .cursor/mcp.json.example as a reference — replace /absolute/path/to/ with your actual workspace path, then adapt the format for each tool:

# Cursor — mcpServers key
cp .cursor/mcp.json.example .cursor/mcp.json
# Edit: replace /absolute/path/to/ with actual path

# Claude Code — identical format, different filename
cp .cursor/mcp.json .mcp.json

# Gemini CLI — identical format, different filename
mkdir -p .gemini && cp .cursor/mcp.json .gemini/settings.json

# GitHub Copilot VS Code — rename root key from "mcpServers" to "servers"
# Edit .vscode/mcp.json with the server entries under "servers": { ... }

# OpenCode — root key "mcp", command is an array, type "local"
# See opencode.json generated by setup.sh for format reference

# Codex CLI — TOML format
# See .codex/config.toml generated by setup.sh for format reference

# Mistral Vibe — TOML format, array-of-tables `[[mcp_servers]]` with name/transport/command/args
# See .vibe/config.toml generated by setup.sh for format reference

All local servers read credentials from .env via python-dotenv — no credentials in config files.

---

Supported Tools

All generated config files contain absolute paths and are gitignored — run ./setup.sh on each machine. AGENTS.md is a shared convention read by both Codex CLI and Mistral Vibe — its instructions are written to be tool-agnostic rather than assuming either one specifically.

The skill workflow is defined once in .agents/skills/develop-neo4j-graph/SKILL.md (the Agent Skills open standard) and referenced by all tools.

---

Project Structure

neo4j-mcp-workspace-template/
├── setup.sh                        # One-time setup script
├── .env.example                    # Documents all environment variables
├── CLAUDE.md                       # Claude Code agent context
├── GEMINI.md                       # Gemini CLI agent context
├── AGENTS.md                       # Codex CLI + Mistral Vibe agent context (shared convention)
├── .agents/
│   └── skills/
│       └── develop-neo4j-graph/    # Cross-tool skill (Agent Skills standard)
│           ├── SKILL.md            # Workflow definition
│           └── references/         # Detailed reference docs per mode
├── .gemini/
│   └── commands/
│       └── develop-neo4j-graph.toml  # Gemini CLI slash command
├── .opencode/
│   └── agents/
│       └── develop-neo4j-graph.md  # OpenCode agent
├── .github/
│   └── copilot-instructions.md     # GitHub Copilot VS Code context
├── data/                           # Input data (gitignored contents, tracked structure)
│   ├── csv/                        # Structured data
│   └── pdf/                        # PDF documents
├── outputs/                        # Generated outputs (gitignored contents, tracked structure)
│   ├── data_models/                # Graph data model JSON files
│   ├── queries/                    # Cypher query YAML files
│   ├── reports/                    # Markdown reports
│   └── schemas/                    # Pydantic extraction schema files
├── demo/                           # Demo data scripts and reference outputs (committed)
│   └── expected/                   # Reference outputs for comparison
├── mcp-neo4j-ingest/               # Local ingest MCP server
├── mcp-neo4j-lexical-graph/        # Local lexical graph MCP server
├── mcp-neo4j-entity-graph/         # Local entity graph MCP server
├── mcp-neo4j-graphrag/             # Cloned by setup.sh (gitignored)
├── .mcp.json                       # Generated (gitignored) — Claude Code MCP config
├── .codex/
│   └── config.toml                 # Generated (gitignored) — Codex CLI MCP config
├── .vibe/
│   └── config.toml                 # Generated (gitignored) — Mistral Vibe MCP config
├── .cursor/
│   ├── mcp.json                    # Generated (gitignored) — Cursor MCP config
│   └── mcp.json.example            # Template for manual setup
├── .gemini/
│   └── settings.json               # Generated (gitignored) — Gemini CLI MCP config
├── .vscode/
│   └── mcp.json                    # Generated (gitignored) — GitHub Copilot MCP config
├── opencode.json                   # Generated (gitignored) — OpenCode MCP config
└── .claude/
    └── skills/
        ├── develop-neo4j-graph/    # Symlink → .agents/skills/develop-neo4j-graph/
        ├── setup-workspace/        # /setup-workspace validation skill
        └── dev/evaluate-pipeline/  # /dev:evaluate-pipeline skill