Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
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.
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.
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
Docker Desktop (with Docker Compose)
Git
(Optional) Python 3.10+ for local development
git clone https://github.com/jfelipenc/neo4j-mcp-knowledge-graph.git
cd neo4j-mcp-knowledge-graphcp .env.example .envEdit .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=testpassword123Important: Change API_KEY to a secure random string. Generate one with:
# Linux/macOS
openssl rand -hex 32
# Windows PowerShell
[guid]::NewGuid().ToString("N")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-hereAlso update .env:
NEO4J_PASSWORD=your-new-password-heredocker-compose up --buildWait 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# 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"}]}'All endpoints (except /health) require the X-API-Key header.
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}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}GET /api/knowledge/search?q=Alice&limit=10
X-API-Key: your-api-keyResponse:
{
"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
The server exposes MCP tools via SSE (Server-Sent Events) transport.
GET /mcp/sse
X-API-Key: your-api-keyThis opens an SSE stream. The MCP client will receive an endpoint event with the URL to POST messages to.
Tool | Description | Parameters |
| Add nodes to the graph |
|
| Add relationships between nodes |
|
| Search nodes by name, return subgraph |
|
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)"
}# Create virtual environment
python -m venv .venv
.venv\Scripts\activate # Windows
# source .venv/bin/activate # Linux/macOS
# Install dependencies
pip install -r requirements.txt# 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# 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/
├── 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.mdAPI 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
# Check logs
docker-compose logs neo4j
# Common fix: remove stale volume and restart
docker-compose down -v
docker-compose up --buildVerify 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
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)
If ports 8000, 7474, or 7687 are in use, edit docker-compose.yml:
api:
ports:
- "8001:8000" # Change 8001 to an available portMIT
This server cannot be installed
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Security firewall for AI agents — scans MCP calls for injection, secrets, and risks.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Self-hosted MCP gateway: turn any API, database or MCP server into AI connectors — no code.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/jfelipenc/neo4j-mcp-knowledge-graph'
If you have feedback or need assistance with the MCP directory API, please join our Discord server