| Name | mcp-neo4j-memory JSON |
| Version |
0.2.0
JSON |
| download |
| home_page | None |
| Summary | MCP Neo4j Knowledge Graph Memory Server |
| upload_time | 2025-07-18 20:24:56 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | None |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 🧠🕸️ Neo4j Knowledge Graph Memory MCP Server
## 🌟 Overview
A Model Context Protocol (MCP) server implementation that provides persistent memory capabilities through Neo4j graph database integration.
By storing information in a graph structure, this server maintains complex relationships between entities as memory nodes and enables long-term retention of knowledge that can be queried and analyzed across multiple conversations or sessions.
With [Neo4j Aura](https://console.neo4j.io) you can host your own database server for free or share it with your collaborators. Otherwise you can run your own Neo4j server locally.
The MCP server leverages Neo4j's graph database capabilities to create an interconnected knowledge base that serves as an external memory system. Through Cypher queries, it allows exploration and retrieval of stored information, relationship analysis between different data points, and generation of insights from the accumulated knowledge. This memory can be further enhanced with Claude's capabilities.
### 🕸️ Graph Schema
* `Memory` - A node representing an entity with a name, type, and observations.
* `Relationship` - A relationship between two entities with a type.
### 🔍 Usage Example
```
Let's add some memories
I, Michael, living in Dresden, Germany work at Neo4j which is headquartered in Sweden with my colleagues Andreas (Cambridge, UK) and Oskar (Gothenburg, Sweden)
I work in Product Management, Oskar in Engineering and Andreas in Developer Relations.
```
Results in Claude calling the create_entities and create_relations tools.
## 📦 Components
### 🔧 Tools
The server offers these core tools:
#### 🔎 Query Tools
- `read_graph`
- Read the entire knowledge graph
- No input required
- Returns: Complete graph with entities and relations
- `search_nodes`
- Search for nodes based on a query
- Input:
- `query` (string): Search query matching names, types, observations
- Returns: Matching subgraph
- `find_nodes`
- Find specific nodes by name
- Input:
- `names` (array of strings): Entity names to retrieve
- Returns: Subgraph with specified nodes
#### ♟️ Entity Management Tools
- `create_entities`
- Create multiple new entities in the knowledge graph
- Input:
- `entities`: Array of objects with:
- `name` (string): Name of the entity
- `type` (string): Type of the entity
- `observations` (array of strings): Initial observations about the entity
- Returns: Created entities
- `delete_entities`
- Delete multiple entities and their associated relations
- Input:
- `entityNames` (array of strings): Names of entities to delete
- Returns: Success confirmation
#### 🔗 Relation Management Tools
- `create_relations`
- Create multiple new relations between entities
- Input:
- `relations`: Array of objects with:
- `source` (string): Name of source entity
- `target` (string): Name of target entity
- `relationType` (string): Type of relation
- Returns: Created relations
- `delete_relations`
- Delete multiple relations from the graph
- Input:
- `relations`: Array of objects with same schema as create_relations
- Returns: Success confirmation
#### 📝 Observation Management Tools
- `add_observations`
- Add new observations to existing entities
- Input:
- `observations`: Array of objects with:
- `entityName` (string): Entity to add to
- `contents` (array of strings): Observations to add
- Returns: Added observation details
- `delete_observations`
- Delete specific observations from entities
- Input:
- `deletions`: Array of objects with:
- `entityName` (string): Entity to delete from
- `observations` (array of strings): Observations to remove
- Returns: Success confirmation
## 🔧 Usage with Claude Desktop
### 💾 Installation
```bash
pip install mcp-neo4j-memory
```
### ⚙️ Configuration
Add the server to your `claude_desktop_config.json` with configuration of:
```json
"mcpServers": {
"neo4j": {
"command": "uvx",
"args": [
"mcp-neo4j-memory@0.2.0",
"--db-url",
"neo4j+s://xxxx.databases.neo4j.io",
"--username",
"<your-username>",
"--password",
"<your-password>"
]
}
}
```
Alternatively, you can set environment variables:
```json
"mcpServers": {
"neo4j": {
"command": "uvx",
"args": [ "mcp-neo4j-memory@0.2.0" ],
"env": {
"NEO4J_URL": "neo4j+s://xxxx.databases.neo4j.io",
"NEO4J_USERNAME": "<your-username>",
"NEO4J_PASSWORD": "<your-password>"
}
}
}
```
### 🌐 HTTP Transport Mode
The server supports HTTP transport for web-based deployments and microservices:
```bash
# Basic HTTP mode (defaults: host=127.0.0.1, port=8000, path=/mcp/)
mcp-neo4j-memory --transport http
# Custom HTTP configuration
mcp-neo4j-memory --transport http --host 0.0.0.0 --port 8080 --path /api/mcp/
```
Environment variables for HTTP configuration:
```bash
export NEO4J_TRANSPORT=http
export NEO4J_MCP_SERVER_HOST=0.0.0.0
export NEO4J_MCP_SERVER_PORT=8080
export NEO4J_MCP_SERVER_PATH=/api/mcp/
mcp-neo4j-memory
```
### 🔄 Transport Modes
The server supports three transport modes:
- **STDIO** (default): Standard input/output for local tools and Claude Desktop
- **SSE**: Server-Sent Events for web-based deployments
- **HTTP**: Streamable HTTP for modern web deployments and microservices
### 🐳 Using with Docker
```json
"mcpServers": {
"neo4j": {
"command": "docker",
"args": [
"run",
"--rm",
"-e", "NEO4J_URL=neo4j+s://xxxx.databases.neo4j.io",
"-e", "NEO4J_USERNAME=<your-username>",
"-e", "NEO4J_PASSWORD=<your-password>",
"mcp/neo4j-memory:0.2.0"
]
}
}
```
## 🚀 Development
### 📦 Prerequisites
1. Install `uv` (Universal Virtualenv):
```bash
# Using pip
pip install uv
# Using Homebrew on macOS
brew install uv
# Using cargo (Rust package manager)
cargo install uv
```
2. Clone the repository and set up development environment:
```bash
# Clone the repository
git clone https://github.com/yourusername/mcp-neo4j-memory.git
cd mcp-neo4j-memory
# Create and activate virtual environment using uv
uv venv
source .venv/bin/activate # On Unix/macOS
.venv\Scripts\activate # On Windows
# Install dependencies including dev dependencies
uv pip install -e ".[dev]"
```
### 🐳 Docker
Build and run the Docker container:
```bash
# Build the image
docker build -t mcp/neo4j-memory:latest .
# Run the container
docker run -e NEO4J_URL="neo4j+s://xxxx.databases.neo4j.io" \
-e NEO4J_USERNAME="your-username" \
-e NEO4J_PASSWORD="your-password" \
mcp/neo4j-memory:latest
```
## 📄 License
This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.
Raw data
{
"_id": null,
"home_page": null,
"name": "mcp-neo4j-memory",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/c3/46/31d699d6afca6503c05c1e7a927ac07bf6dad68411337a850465c90ca691/mcp_neo4j_memory-0.2.0.tar.gz",
"platform": null,
"description": "# \ud83e\udde0\ud83d\udd78\ufe0f Neo4j Knowledge Graph Memory MCP Server\n\n## \ud83c\udf1f Overview\n\nA Model Context Protocol (MCP) server implementation that provides persistent memory capabilities through Neo4j graph database integration.\n\nBy storing information in a graph structure, this server maintains complex relationships between entities as memory nodes and enables long-term retention of knowledge that can be queried and analyzed across multiple conversations or sessions.\n\nWith [Neo4j Aura](https://console.neo4j.io) you can host your own database server for free or share it with your collaborators. Otherwise you can run your own Neo4j server locally.\n\nThe MCP server leverages Neo4j's graph database capabilities to create an interconnected knowledge base that serves as an external memory system. Through Cypher queries, it allows exploration and retrieval of stored information, relationship analysis between different data points, and generation of insights from the accumulated knowledge. This memory can be further enhanced with Claude's capabilities.\n\n### \ud83d\udd78\ufe0f Graph Schema\n\n* `Memory` - A node representing an entity with a name, type, and observations.\n* `Relationship` - A relationship between two entities with a type.\n\n### \ud83d\udd0d Usage Example\n\n```\nLet's add some memories \nI, Michael, living in Dresden, Germany work at Neo4j which is headquartered in Sweden with my colleagues Andreas (Cambridge, UK) and Oskar (Gothenburg, Sweden)\nI work in Product Management, Oskar in Engineering and Andreas in Developer Relations.\n```\n\nResults in Claude calling the create_entities and create_relations tools.\n\n\n\n\n\n## \ud83d\udce6 Components\n\n### \ud83d\udd27 Tools\n\nThe server offers these core tools:\n\n#### \ud83d\udd0e Query Tools\n- `read_graph`\n - Read the entire knowledge graph\n - No input required\n - Returns: Complete graph with entities and relations\n\n- `search_nodes`\n - Search for nodes based on a query\n - Input:\n - `query` (string): Search query matching names, types, observations\n - Returns: Matching subgraph\n\n- `find_nodes`\n - Find specific nodes by name\n - Input:\n - `names` (array of strings): Entity names to retrieve\n - Returns: Subgraph with specified nodes\n\n#### \u265f\ufe0f Entity Management Tools\n- `create_entities`\n - Create multiple new entities in the knowledge graph\n - Input:\n - `entities`: Array of objects with:\n - `name` (string): Name of the entity\n - `type` (string): Type of the entity \n - `observations` (array of strings): Initial observations about the entity\n - Returns: Created entities\n\n- `delete_entities` \n - Delete multiple entities and their associated relations\n - Input:\n - `entityNames` (array of strings): Names of entities to delete\n - Returns: Success confirmation\n\n#### \ud83d\udd17 Relation Management Tools\n- `create_relations`\n - Create multiple new relations between entities\n - Input:\n - `relations`: Array of objects with:\n - `source` (string): Name of source entity\n - `target` (string): Name of target entity\n - `relationType` (string): Type of relation\n - Returns: Created relations\n\n- `delete_relations`\n - Delete multiple relations from the graph\n - Input:\n - `relations`: Array of objects with same schema as create_relations\n - Returns: Success confirmation\n\n#### \ud83d\udcdd Observation Management Tools\n- `add_observations`\n - Add new observations to existing entities\n - Input:\n - `observations`: Array of objects with:\n - `entityName` (string): Entity to add to\n - `contents` (array of strings): Observations to add\n - Returns: Added observation details\n\n- `delete_observations`\n - Delete specific observations from entities\n - Input:\n - `deletions`: Array of objects with:\n - `entityName` (string): Entity to delete from\n - `observations` (array of strings): Observations to remove\n - Returns: Success confirmation\n\n## \ud83d\udd27 Usage with Claude Desktop\n\n### \ud83d\udcbe Installation\n\n```bash\npip install mcp-neo4j-memory\n```\n\n### \u2699\ufe0f Configuration\n\nAdd the server to your `claude_desktop_config.json` with configuration of:\n\n```json\n\"mcpServers\": {\n \"neo4j\": {\n \"command\": \"uvx\",\n \"args\": [\n \"mcp-neo4j-memory@0.2.0\",\n \"--db-url\",\n \"neo4j+s://xxxx.databases.neo4j.io\",\n \"--username\",\n \"<your-username>\",\n \"--password\",\n \"<your-password>\"\n ]\n }\n}\n```\n\nAlternatively, you can set environment variables:\n\n```json\n\"mcpServers\": {\n \"neo4j\": {\n \"command\": \"uvx\",\n \"args\": [ \"mcp-neo4j-memory@0.2.0\" ],\n \"env\": {\n \"NEO4J_URL\": \"neo4j+s://xxxx.databases.neo4j.io\",\n \"NEO4J_USERNAME\": \"<your-username>\",\n \"NEO4J_PASSWORD\": \"<your-password>\"\n }\n }\n}\n```\n\n### \ud83c\udf10 HTTP Transport Mode\n\nThe server supports HTTP transport for web-based deployments and microservices:\n\n```bash\n# Basic HTTP mode (defaults: host=127.0.0.1, port=8000, path=/mcp/)\nmcp-neo4j-memory --transport http\n\n# Custom HTTP configuration\nmcp-neo4j-memory --transport http --host 0.0.0.0 --port 8080 --path /api/mcp/\n```\n\nEnvironment variables for HTTP configuration:\n\n```bash\nexport NEO4J_TRANSPORT=http\nexport NEO4J_MCP_SERVER_HOST=0.0.0.0\nexport NEO4J_MCP_SERVER_PORT=8080\nexport NEO4J_MCP_SERVER_PATH=/api/mcp/\nmcp-neo4j-memory\n```\n\n### \ud83d\udd04 Transport Modes\n\nThe server supports three transport modes:\n\n- **STDIO** (default): Standard input/output for local tools and Claude Desktop\n- **SSE**: Server-Sent Events for web-based deployments \n- **HTTP**: Streamable HTTP for modern web deployments and microservices\n\n### \ud83d\udc33 Using with Docker\n\n```json\n\"mcpServers\": {\n \"neo4j\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-e\", \"NEO4J_URL=neo4j+s://xxxx.databases.neo4j.io\",\n \"-e\", \"NEO4J_USERNAME=<your-username>\",\n \"-e\", \"NEO4J_PASSWORD=<your-password>\",\n \"mcp/neo4j-memory:0.2.0\"\n ]\n }\n}\n```\n\n## \ud83d\ude80 Development\n\n### \ud83d\udce6 Prerequisites\n\n1. Install `uv` (Universal Virtualenv):\n```bash\n# Using pip\npip install uv\n\n# Using Homebrew on macOS\nbrew install uv\n\n# Using cargo (Rust package manager)\ncargo install uv\n```\n\n2. Clone the repository and set up development environment:\n```bash\n# Clone the repository\ngit clone https://github.com/yourusername/mcp-neo4j-memory.git\ncd mcp-neo4j-memory\n\n# Create and activate virtual environment using uv\nuv venv\nsource .venv/bin/activate # On Unix/macOS\n.venv\\Scripts\\activate # On Windows\n\n# Install dependencies including dev dependencies\nuv pip install -e \".[dev]\"\n```\n\n### \ud83d\udc33 Docker\n\nBuild and run the Docker container:\n\n```bash\n# Build the image\ndocker build -t mcp/neo4j-memory:latest .\n\n# Run the container\ndocker run -e NEO4J_URL=\"neo4j+s://xxxx.databases.neo4j.io\" \\\n -e NEO4J_USERNAME=\"your-username\" \\\n -e NEO4J_PASSWORD=\"your-password\" \\\n mcp/neo4j-memory:latest\n```\n\n## \ud83d\udcc4 License\n\nThis MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.\n",
"bugtrack_url": null,
"license": null,
"summary": "MCP Neo4j Knowledge Graph Memory Server",
"version": "0.2.0",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9de805fb72c589c3b05836b46e1dec088a975c8bbe3398cde688110ee8856d8f",
"md5": "7af3d0fd09e9357907eba51b2f349688",
"sha256": "0379a6a6b36d0b23bd7b8c50157312dd5ea0236642c8014169ef96144610bd88"
},
"downloads": -1,
"filename": "mcp_neo4j_memory-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7af3d0fd09e9357907eba51b2f349688",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 8242,
"upload_time": "2025-07-18T20:24:55",
"upload_time_iso_8601": "2025-07-18T20:24:55.764198Z",
"url": "https://files.pythonhosted.org/packages/9d/e8/05fb72c589c3b05836b46e1dec088a975c8bbe3398cde688110ee8856d8f/mcp_neo4j_memory-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c34631d699d6afca6503c05c1e7a927ac07bf6dad68411337a850465c90ca691",
"md5": "30cf1c9cdf4349e98a486e4145d8b110",
"sha256": "329a22cb94d36db1ad95506e51e7ab12026c5231ef3fef3478e805131b539ae5"
},
"downloads": -1,
"filename": "mcp_neo4j_memory-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "30cf1c9cdf4349e98a486e4145d8b110",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 894720,
"upload_time": "2025-07-18T20:24:56",
"upload_time_iso_8601": "2025-07-18T20:24:56.658200Z",
"url": "https://files.pythonhosted.org/packages/c3/46/31d699d6afca6503c05c1e7a927ac07bf6dad68411337a850465c90ca691/mcp_neo4j_memory-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-18 20:24:56",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "mcp-neo4j-memory"
}
