Neo4j Knowledge

You run an MCP server backed by Neo4j to store and query a knowledge graph. It provides a stdio-based interface so you can send MCP messages to create entities, define relationships, search and update your graph, introspect the schema, and manage data lifecycle directly against a Neo4j database.

How to use

To use this MCP server, run it in stdio mode and connect your MCP client to the standard input/output streams. The server exposes commands for creating entities, creating relations, searching entities, updating entities, deleting entities, and introspecting the database schema. Your client sends structured MCP messages and receives responses with results or errors. Start the server first, then begin issuing requests for operations you need to perform on the knowledge graph.

How to install

Prerequisites include Python 3.8 or newer and a running (local or remote) Neo4j database. You will also need Poetry to manage dependencies and optional tooling for task automation.

Step by step commands you can run:

# Install Poetry for Python dependency management (if not already installed)
curl -sSL https://install.python-poetry.org | python3 -

# Create a project directory and install dependencies
poetry install

# Start the MCP server (see the dedicated start command below)
poetry run python mcp_neo4j_knowledge_graph/mcp/server.py

Configuration

Configure how you run the MCP server. You typically point your client or orchestration tooling to the stdio-based server command, and you ensure a Neo4j instance is available for backend storage.

The following example demonstrates how to run the server in the intended way when integrating with a desktop configuration that launches the built executable. Build the standalone executable first, then reference the path in your configuration.

Build the standalone executable (example flow)

# If you use a task runner to build artifacts
task build

# This creates the binary at dist/neo4j_mcp_server

Running the MCP server directly

Start the MCP server directly from Python using Poetry to ensure the correct virtual environment and dependencies are loaded.

poetry run python mcp_neo4j_knowledge_graph/mcp/server.py

Available Tools

The MCP server provides a set of tools to manage the Neo4j-backed knowledge graph. Each tool encapsulates a specific operation on the graph.

Entities and relationships tooling overview

• Create Entities: Add new nodes with a type and properties. The id can be derived from the name if not provided.

• Create Relations: Link existing entities with a labeled relationship, defining the direction through source and target.

• Search Entities: Query the graph with optional text terms, type filters, and property filters. You can also include related nodes and relationships.

• Update Entities: Modify properties or labels on existing entities.

• Delete Entities: Remove entities with optional cascade deletion of related relationships.

• Introspect Schema: Retrieve the current graph schema, including node labels, relationship types, and their properties.

Testing

Run the provided test tasks to verify client, config, and database functionality. Use the task runner to manage tests and development flow.

Available tools

Create Entities

Adds new nodes to the knowledge graph. Each entity must have a type and properties. The ID is derived from the name if not provided.

Create Relations

Creates relationships between existing entities by specifying type, source, and target IDs.

Search Entities

Performs text-based and property-based searches across entities, with optional type and relationship inclusion filters.

Update Entities

Updates properties and labels on existing entities, including adding or removing properties and labels.

Delete Entities

Deletes entities with optional cascade deletion of connected relationships and a dry-run mode to preview impact.

Introspect Schema

Retrieves the current Neo4j schema, including node labels, relationship types, and their properties.