Content
# Neo4j MCP Server
This is a Memory Control Protocol (MCP) server implementation that uses Neo4j as the backend storage for knowledge graph management. It provides a stdio-based interface for storing and retrieving knowledge in a graph database format.
## Prerequisites
- Python 3.8+
- Neo4j Database (local or remote)
- Poetry (Python package manager)
- Docker and Docker Compose (for running Neo4j)
- Go Task (optional, for task automation)
## Installation
1. Clone the repository:
```bash
git clone <repository-url>
cd neo4j_mcp_server
```
2. Install Poetry if you haven't already:
```bash
curl -sSL https://install.python-poetry.org | python3 -
```
3. Install dependencies:
```bash
poetry install
```
## Configuration
### Claude Desktop Configuration
For Ubuntu users running Claude Desktop, you can configure the MCP server by adding it to your Claude desktop configuration file at:
```
~/.config/Claude/claude_desktop_config.json
```
Before configuring, you need to build the standalone executable:
```bash
task build
```
This will create a binary at `dist/neo4j_mcp_server`. Make sure to update the path in your configuration to point to this built executable.
An example configuration is provided in `example_mcp_config.json`. You can copy and modify this file:
```bash
cp example_mcp_config.json ~/.config/Claude/claude_desktop_config.json
```
Then edit the `command` path in the configuration file to point to your built executable:
```json
{
"mcpServers": [
{
"name": "neo4j-knowledge-graph",
"command": ["/path/to/your/dist/neo4j_mcp_server"],
...
}
]
}
```
The configuration includes:
- Server name and description
- Command to start the server (path to the built executable)
- Available tools and their parameters
- Required fields and data types
## Running the Server
### Using Task (Recommended)
If you have Go Task installed, you can use the provided Taskfile to manage the server:
```bash
# Show available tasks
task
# Start everything (Docker + Server)
task run
# Start development environment (Docker + Server + Test)
task dev
# Stop all services
task down
```
### Using Docker Compose directly
1. Start the Neo4j container:
```bash
docker-compose up -d
```
2. Wait for Neo4j to be ready (the container will show as "healthy" in `docker ps`)
### Running the MCP Server directly
Start the server with:
```bash
poetry run python mcp_neo4j_knowledge_graph/mcp/server.py
```
The server will start in stdio mode, ready to accept MCP protocol messages.
## Available Tools
### 1. Create Entities
Creates new entities in the knowledge graph. Each entity must have a type and properties. The ID will be automatically set from the name property if not explicitly provided.
Parameters:
- `entities`: List of entity objects, each containing:
- `type`: String - The type of entity (e.g., Person, Organization)
- `properties`: Object - Key-value pairs of entity properties (must include either 'id' or 'name')
Example input:
```json
{
"entities": [{
"type": "Person",
"properties": {
"name": "John Doe",
"occupation": "Developer",
"age": 30
}
}]
}
```
### 2. Create Relations
Creates relationships between existing entities in the knowledge graph. All referenced entities must exist before creating relations.
Parameters:
- `relations`: List of relation objects, each containing:
- `type`: String - The type of relation (e.g., KNOWS, WORKS_FOR)
- `from`: String - ID of the source entity
- `to`: String - ID of the target entity
Example input:
```json
{
"relations": [{
"type": "KNOWS",
"from": "john_doe",
"to": "jane_smith"
}]
}
```
### 3. Search Entities
Searches for entities in the knowledge graph with powerful text matching and filtering capabilities. Can be used to search by text, list entities by type, find entities with specific properties, or any combination of these filters.
Parameters:
- `search_term`: String (optional) - Text to search for in entity properties. If not provided, returns entities based on other filters.
- `entity_type`: String (optional) - Filter results by entity type (e.g., Person, Organization). If provided alone, returns all entities of that type.
- `properties`: List[String] (optional) - List of property names to filter by:
- With search_term: Searches these properties for the term
- Without search_term: Returns entities that have any of these properties defined
- `include_relationships`: Boolean (optional, default: false) - Whether to include connected entities and relationships
- `fuzzy_match`: Boolean (optional, default: true) - Whether to use case-insensitive partial matching when search_term is provided
Example inputs:
```json
// Search by text with type filter
{
"search_term": "John",
"entity_type": "Person",
"properties": ["name", "occupation"],
"include_relationships": true
}
// List all entities of a type
{
"entity_type": "Person"
}
// Find entities with specific properties
{
"properties": ["email", "phone"],
"entity_type": "Contact"
}
// Combine filters
{
"entity_type": "Person",
"properties": ["email"],
"search_term": "example.com",
"fuzzy_match": true
}
// Return all entities (no filters)
{}
```
Returns:
```json
{
"results": [
{
"id": "john_doe",
"type": ["Entity", "Person"],
"properties": {
"name": "John Doe",
"email": "john@example.com"
},
"relationships": [ // Only included if include_relationships is true
{
"type": "WORKS_AT",
"direction": "outgoing",
"node": {
"id": "tech_corp",
"type": "Company",
"properties": {
"name": "Tech Corp"
}
}
}
]
}
]
}
```
Notes:
- When no filters are provided, returns all entities
- Entity type filtering is exact match (not fuzzy)
- Property existence check is done with `IS NOT NULL`
- Text search supports case-insensitive partial matching when fuzzy_match is true
- Empty results are returned as an empty array, not an error
- Performance considerations:
- Filtering by type is more efficient than text search
- Property existence checks are optimized
- Consider using specific properties instead of searching all properties
- Large result sets may be paginated in future versions
### 4. Update Entities
Updates existing entities in the knowledge graph. Supports adding/removing properties and labels.
Parameters:
- `updates`: List of update objects, each containing:
- `id`: String (required) - ID of the entity to update
- `properties`: Object (optional) - Properties to update or add
- `remove_properties`: List[String] (optional) - Property names to remove
- `add_labels`: List[String] (optional) - Labels to add to the entity
- `remove_labels`: List[String] (optional) - Labels to remove from the entity
Example input:
```json
{
"updates": [{
"id": "john_doe",
"properties": {
"occupation": "Senior Developer",
"salary": 100000
},
"remove_properties": ["temporary_note"],
"add_labels": ["Verified"],
"remove_labels": ["Pending"]
}]
}
```
### 5. Delete Entities
Deletes entities from the knowledge graph with optional cascade deletion of relationships.
Parameters:
- `entity_ids`: List[String] (required) - List of entity IDs to delete
- `cascade`: Boolean (optional, default: false) - Whether to delete connected relationships
- `dry_run`: Boolean (optional, default: false) - Preview deletion impact without making changes
Example input:
```json
{
"entity_ids": ["john_doe", "jane_smith"],
"cascade": true,
"dry_run": true
}
```
Returns:
- `success`: Boolean - Whether the operation was successful
- `deleted_entities`: List of deleted entities
- `deleted_relationships`: List of deleted relationships
- `errors`: List of error messages (if any)
- `impacted_entities`: List of entities that would be affected (dry_run only)
- `impacted_relationships`: List of relationships that would be affected (dry_run only)
### 6. Introspect Schema
Retrieves comprehensive information about the Neo4j database schema, including node labels, relationship types, and their properties.
Parameters: None required
Returns:
- `schema`: Object containing:
- `node_labels`: List of all node labels in the database
- `relationship_types`: List of all relationship types
- `node_properties`: Map of label to list of property names
- `relationship_properties`: Map of relationship type to list of property names
Example input:
```json
{}
```
## Testing
### Test Scripts
The project includes several test scripts for different aspects of the system:
1. `mcp_neo4j_knowledge_graph/test_mcp_client.py` - Tests the MCP client functionality
- Verifies server startup
- Tests tool listing
- Tests schema introspection
- Tests entity creation
```bash
task test-client # Run just the client test
```
2. `mcp_neo4j_knowledge_graph/test_mcp_config.py` - Tests the MCP configuration
- Validates configuration file loading
- Tests server connection using the official MCP SDK
- Verifies all required tools are available
```bash
task test-config # Run just the config test
```
3. `mcp_neo4j_knowledge_graph/test_neo4j_connection.py` - Tests the Neo4j database connection
- Verifies database connectivity
- Tests basic query functionality
- Checks environment configuration
```bash
task test-db # Run just the database test
```
### Running Tests
You can run the tests in several ways:
1. Run all tests together:
```bash
task test # Runs all tests including pytest and integration tests
```
2. Run individual test types:
```bash
task test-client # Run MCP client test
task test-config # Run MCP config test
task test-db # Run Neo4j connection test
task test-integration # Run integration tests
```
3. Run tests with pytest directly:
```bash
poetry run pytest # Run all pytest-compatible tests
```
## Development
### Using Task
The project includes several development tasks:
```bash
# Format code
task format
# Run linter
task lint
# Run tests
task test
# Start development environment
task dev
```
### Running directly
This project uses several development tools that are automatically installed with Poetry:
- `black` for code formatting
- `isort` for import sorting
- `flake8` for linting
- `pytest` for testing
You can run these tools using Poetry:
```bash
# Format code
poetry run black .
# Sort imports
poetry run isort .
# Run linter
poetry run flake8
# Run tests
poetry run pytest
```
## Error Handling
The server includes comprehensive error handling for:
- Database connection issues
- Invalid queries
- Missing nodes
- Invalid request formats
- Schema validation errors
- Relationship creation failures
- Entity update conflicts
All errors are returned with appropriate error messages in the MCP protocol format.
## Docker Configuration
The Neo4j container is configured with the following settings:
- Ports: 7474 (HTTP) and 7687 (Bolt)
- Default credentials: neo4j/password
- APOC plugin enabled
- File import/export enabled
- Health check configured
You can modify these settings in the `docker-compose.yml` file.
## Task Commands Reference
- `task` - Show available tasks
- `task run` - Start Docker and MCP server
- `task dev` - Start development environment (Docker + Server + Test)
- `task docker` - Start Neo4j database
- `task server` - Run the MCP server
- `task test` - Run all tests
- `task test-client` - Run MCP client tests
- `task test-config` - Run MCP config tests
- `task test-db` - Run database tests
- `task test-integration` - Run integration tests
- `task down` - Stop all Docker services
- `task format` - Format code using black and isort
- `task lint` - Run flake8 linter
- `task help` - Show detailed help for all tasks
