mcp-neo4j-memory

This MCP server provides a persistent, graph-based memory system for AI assistants using Neo4j with the Graph Data Science plugin. It exposes four unified MCP tools designed to manage memories: memory_store to create memories with observations and immediate relations in a single operation; memory_find to perform semantic and exact searches, date filtering, and graph traversals; memory_modify to update, delete, or adjust observations and relations; and database_switch to move between isolated project databases. The combination of graph storage and vector-enabled search enables rich memory lifecycles, including tracking temporal metadata and complex relationships between memories. To use it, connect via Claude Desktop or MCP clients, switch to your project database, and start storing and querying memories with the provided tools. The server emphasizes explicit errors and transparent operations to aid debugging, rather than silent fallbacks.

Prerequisites:

• Node.js and npm installed on your system
• Access to a Neo4j instance with the Graph Data Science (GDS) plugin configured

Step 1: Install the MCP server package

npm install @sylweriusz/mcp-neo4j-memory-server

Step 2: Run the server (example using npx as configured by the integration)

# If you are using the provided mcp_config, you can start via your MCP runner.
# Alternatively, locally you can run the package with npm or npx if needed:
npx -y @sylweriusz/mcp-neo4j-memory-server

Step 3: Ensure Neo4j/GDS setup is ready

• Start a DozerDB instance with the Graph Data Science plugin (GDS) enabled
  • See the DozerDB setup guide at https://dozerdb.org/
• Verify DozerDB/GDS readiness before connecting the MCP server

Step 4: Configure connection details

• Provide the Neo4j connection details in your MCP config or environment variables, for example:

NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-password

Step 5: Configure in Claude Desktop (example)

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@sylweriusz/mcp-neo4j-memory-server"],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "your-password"
      }
    }
  }
}

Optional: If you prefer Docker-based Neo4j with DozerDB, see the Neo4j Setup section in the README for the docker run commands to launch DozerDB with GDS.

Tips and common issues:

• Vector search relies on the GDS plugin; ensure the plugin is properly installed and accessible to the Neo4j instance.
• If you encounter [VectorSearch] GDS Plugin detected errors, re-check that GDS is enabled in the Neo4j configuration (dozerdb deployment instructions apply).
• Connection issues usually stem from incorrect Neo4j credentials or URI; verify the NEO4J_URI, NEO4J_USERNAME, and NEO4J_PASSWORD environment variables.
• For memory organization, use database_switch to isolate projects; this helps prevent cross-project data leakage.
• When debugging, consult MCP logs for explicit errors, as the server emphasizes zero-fallback behavior to aid troubleshooting.