How do I use Neo4j MCP Knowledge Graph Server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Neo4j MCP Knowledge Graph Server Add nodes for Alice (Person) and ChatGPT (AI) and connect them with USES." That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Neo4j MCP Knowledge Graph Server

by jfelipenc

Overview Schema Source Related Servers Discussions Admin

Python

Neo4j MCP Knowledge Graph Server

A containerized FastAPI + MCP (Model Context Protocol) server that lets LLM agents inject structured knowledge (Entities and Relationships) into a Neo4j graph database with APOC-based safe Cypher execution.

Features

Dual API: REST endpoints + MCP SSE transport for LLM agent integration
Safe Cypher: APOC procedures prevent Cypher injection with dynamic labels/types
Full-text search: Cross-label search via Neo4j full-text index
Schema flexibility: Agents can invent node labels and relationship types (tagged with is_generated: true)
API key auth: All traffic protected by X-API-Key header
Docker Compose: One-command deployment with Neo4j 5 + APOC

Related MCP server: buddy

Prerequisites

Docker Desktop (with Docker Compose)
Git
(Optional) Python 3.10+ for local development

Quick Start

1. Clone the repository

git clone https://github.com/jfelipenc/neo4j-mcp-knowledge-graph.git
cd neo4j-mcp-knowledge-graph

2. Configure environment

cp .env.example .env

Edit .env and set your values:

# Required: Change this to a secure random string
API_KEY=your-secure-api-key-here

# Neo4j connection (defaults work with docker-compose)
NEO4J_URI=bolt://neo4j:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=testpassword123

Important: Change API_KEY to a secure random string. Generate one with:

# Linux/macOS
openssl rand -hex 32

# Windows PowerShell
[guid]::NewGuid().ToString("N")

3. Change the Neo4j password (optional but recommended)

Edit docker-compose.yml and update both services:

neo4j:
  environment:
    - NEO4J_AUTH=neo4j/your-new-password-here
    ...
  healthcheck:
    test: ["CMD", "cypher-shell", "-u", "neo4j", "-p", "your-new-password-here", "RETURN 1"]

api:
  environment:
    - NEO4J_PASSWORD=your-new-password-here

Also update .env:

NEO4J_PASSWORD=your-new-password-here

4. Start the stack

docker-compose up --build

Wait for Neo4j to be healthy (the API service depends on it):

neo4j-mcp-knowledge-graph-neo4j-1  | Started.
neo4j-mcp-knowledge-graph-api-1    | INFO:     Uvicorn running on http://0.0.0.0:8000

5. Verify it's running

# Health check (no auth required)
curl http://localhost:8000/health

# Test auth (replace with your API key)
curl -X POST http://localhost:8000/api/knowledge/entities \
  -H "X-API-Key: your-secure-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"entities": [{"name": "Alice", "label": "Person"}]}'

API Documentation

Authentication

All endpoints (except /health) require the X-API-Key header.

REST Endpoints

Add Entities

POST /api/knowledge/entities
Content-Type: application/json
X-API-Key: your-api-key

{
  "entities": [
    {
      "name": "Alice",
      "label": "Person",
      "properties": {"age": 30, "city": "NYC"},
      "is_generated": false
    },
    {
      "name": "GraphDB",
      "label": "Technology",
      "properties": {"vendor": "Neo4j"},
      "is_generated": true
    }
  ]
}

Response:

{"count": 2}

Add Relations

POST /api/knowledge/relations
Content-Type: application/json
X-API-Key: your-api-key

{
  "relations": [
    {
      "source_name": "Alice",
      "source_label": "Person",
      "target_name": "GraphDB",
      "target_label": "Technology",
      "relation_type": "USES",
      "properties": {"since": "2024"},
      "is_generated": false
    }
  ]
}

Response:

{"count": 1}

Search Graph

GET /api/knowledge/search?q=Alice&limit=10
X-API-Key: your-api-key

Response:

{
  "nodes": [
    {
      "name": "Alice",
      "label": "Person",
      "properties": {"age": 30, "city": "NYC"}
    }
  ],
  "edges": [
    {
      "source": "Alice",
      "target": "GraphDB",
      "type": "USES",
      "properties": {"since": "2024"}
    }
  ]
}

Search tips:

Use * for prefix matching: Alice* finds Alice, AliceSmith
Search is case-insensitive on the full-text index
Limit defaults to 10, max 100

MCP (Model Context Protocol)

The server exposes MCP tools via SSE (Server-Sent Events) transport.

Connect to SSE

GET /mcp/sse
X-API-Key: your-api-key

This opens an SSE stream. The MCP client will receive an endpoint event with the URL to POST messages to.

MCP Tools

Tool	Description	Parameters
`add_entities`	Add nodes to the graph	`entities: list[Entity]`
`add_relations`	Add relationships between nodes	`relations: list[Relation]`
`search_graph`	Search nodes by name, return subgraph	`query: str, limit: int = 10`

Entity schema:

{
  "name": "string (required)",
  "label": "string (required)",
  "properties": {"key": "value"},
  "is_generated": "boolean (default: false)"
}

Relation schema:

{
  "source_name": "string (required)",
  "source_label": "string (required)",
  "target_name": "string (required)",
  "target_label": "string (required)",
  "relation_type": "string (required)",
  "properties": {"key": "value"},
  "is_generated": "boolean (default: false)"
}

Local Development

Setup

# Create virtual environment
python -m venv .venv
.venv\Scripts\activate  # Windows
# source .venv/bin/activate  # Linux/macOS

# Install dependencies
pip install -r requirements.txt

Run tests

# Unit tests (fast, no Docker required)
pytest tests/ -m "not integration" -v

# Integration tests (requires Docker, spins up Neo4j container)
pytest tests/ -m integration -v

# All tests
pytest tests/ -v

Run locally (without Docker)

# Start Neo4j separately (e.g., via Docker)
docker run -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/testpassword123 \
  -e NEO4J_PLUGINS='["apoc"]' \
  -e NEO4J_dbms_security_procedures_unrestricted=apoc.* \
  neo4j:5

# Set environment variables
$env:API_KEY="dev-api-key"
$env:NEO4J_URI="bolt://localhost:7687"
$env:NEO4J_USER="neo4j"
$env:NEO4J_PASSWORD="testpassword123"

# Run the app
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Project Structure

/
├── app/
│   ├── __init__.py
│   ├── main.py          # FastAPI app, auth, REST endpoints, MCP SSE wiring
│   ├── mcp_server.py    # MCP tools (add_entities, add_relations, search_graph)
│   ├── database.py      # Neo4j driver, APOC merges, full-text search
│   └── schemas.py       # Pydantic models (Entity, Relation)
├── tests/
│   ├── test_schemas.py
│   ├── test_database.py
│   ├── test_mcp_server.py
│   ├── test_main.py
│   └── test_integration.py
├── docker-compose.yml   # Neo4j 5 + APOC + API service
├── Dockerfile           # Python 3.11 app container
├── requirements.txt
├── .env.example         # Environment template
└── README.md

Security Notes

API key: Always change the default API_KEY in production
Neo4j password: Change the default testpassword123 in production
Cypher injection: APOC procedures prevent injection via dynamic labels/types
Timing attacks: API key comparison uses secrets.compare_digest
Auth coverage: All routes except /health require authentication

Troubleshooting

Neo4j container won't start

# Check logs
docker-compose logs neo4j

# Common fix: remove stale volume and restart
docker-compose down -v
docker-compose up --build

API can't connect to Neo4j

Verify Neo4j is healthy: docker-compose ps
Check the password matches in both docker-compose.yml and .env
Ensure NEO4J_URI uses the service name (bolt://neo4j:7687) not localhost

Full-text search returns no results

Neo4j full-text indexes are eventually consistent — wait a moment after writes
Use prefix wildcards: Alice* instead of Alice for partial matching
Verify the index exists: SHOW INDEXES in Neo4j Browser (http://localhost:7474)

Port conflicts

If ports 8000, 7474, or 7687 are in use, edit docker-compose.yml:

api:
  ports:
    - "8001:8000"  # Change 8001 to an available port

License

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityStale

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

jumpcloud-genaiOAuth
com.jumpcloud
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
Cloud Platforms Security Developer Tools
2
secureflows-mcp A
io.github.michal-lefler
MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.
Code Analysis Developer Tools Security
181
Relm CRM A
com.relmcrm
API-first CRM for LLMs - contacts, companies, deals and activities over a native MCP server.
CRM AI & Machine Learning
412
Agent Safe AOAuth
io.github.wowcool
Email safety MCP server. Detects phishing, prompt injection, CEO fraud for AI agents.
Security Autonomous Agents
2

Related MCP Servers

Neo4j GraphRAG MCP Server
RAG Systems Databases Vector Databases
neo4j-field
A
license
A
quality
C
maintenance
An MCP server that enables LLMs to perform semantic and fulltext searches within Neo4j while executing complex, search-augmented Cypher queries for GraphRAG applications. It provides tools for database schema discovery and supports multi-provider embeddings to facilitate advanced graph traversals.
Updated 2 months ago (2026-07-17 09:29 UTC)
5
3
MIT
buddy
Knowledge & Memory Agent Orchestration
enki-run
A
license
Not graded
quality
F
maintenance
Agent-first knowledge graph MCP server that provides 25 tools for managing a knowledge graph with nodes and edges, plus a human-readable dashboard for LLMs and AI agents.
Updated 3 months ago (2026-06-20 13:01 UTC)
459 npm
Apache 2.0
Neo4j MCP Server
Databases Knowledge & Memory
alvaropaco
A
license
A
quality
B
maintenance
MCP server for Neo4j that provides abstract graph operations for LLMs, enabling safe and consistent interaction with Neo4j databases through tools like search, insert, update, delete, and schema introspection.
Updated a month ago (2026-08-25 16:41 UTC)
8
MIT
Temporal Knowledge Substrate
Knowledge & Memory Databases AI & Machine Learning
kenningai
F
license
Not graded
quality
C
maintenance
An MCP server that lets LLM agents accumulate organizational knowledge across sessions, scoped by domain, backed by Neo4j with enforced structural invariants.
Updated 2 months ago (2026-08-10 19:42 UTC)
-

Neo4j MCP Knowledge Graph Server

Features

Prerequisites

Quick Start

1. Clone the repository

2. Configure environment

3. Change the Neo4j password (optional but recommended)

4. Start the stack

5. Verify it's running

API Documentation

Authentication

REST Endpoints

Add Entities

Add Relations

Search Graph

MCP (Model Context Protocol)

Connect to SSE

MCP Tools

Local Development

Setup

Run tests

Run locally (without Docker)

Project Structure

Security Notes

Troubleshooting

Neo4j container won't start

API can't connect to Neo4j

Full-text search returns no results

Port conflicts

License

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Neo4j GraphRAG MCP Server

buddy

Neo4j MCP Server

Temporal Knowledge Substrate