Connect Claude Desktop to Your Knowledge Graph

A step-by-step tutorial to connect Claude Desktop to a Neo4j knowledge graph using the MCP server.

In this tutorial, we’ll set up the neo4j-agent-memory MCP server so that Claude Desktop can store conversations, extract entities, learn preferences, and query your knowledge graph — all automatically.

What You’ll Learn

  • How to install and start the MCP server

  • How to configure Claude Desktop to connect to it

  • How memory is captured automatically during conversations

  • How to verify entities and preferences in Neo4j Browser

Prerequisites

  • Python 3.10 or higher

  • Docker (for running Neo4j locally)

  • Claude Desktop installed

Time Required

Approximately 15 minutes.

Step 1: Start Neo4j

Start a local Neo4j instance using Docker:

docker run -d \
  --name neo4j-memory \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/test-password \
  -e NEO4J_PLUGINS='["apoc"]' \
  neo4j:5

Wait for Neo4j to start (about 30 seconds), then verify at http://localhost:7474.

Step 2: Install neo4j-agent-memory

Install the package with MCP support:

pip install neo4j-agent-memory[mcp]

Verify the installation:

neo4j-agent-memory mcp serve --help

You should see the available options for the MCP server.

Step 3: Configure Claude Desktop

Open your Claude Desktop configuration file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the neo4j-agent-memory server:

{
  "mcpServers": {
    "neo4j-agent-memory": {
      "command": "neo4j-agent-memory",
      "args": ["mcp", "serve",
               "--password", "test-password"],
      "env": {}
    }
  }
}

Restart Claude Desktop to pick up the configuration.

If you installed with uvx, use "command": "uvx" and "args": ["neo4j-agent-memory[mcp]", "mcp", "serve", "--password", "test-password"] instead.

Step 4: Verify the Connection

In Claude Desktop, start a new conversation and ask:

What do you remember about me?

Claude should call the memory_search tool and report that no memories are stored yet. This confirms the MCP server is connected and working.

Step 5: Have a Memory-Aware Conversation

Now have a natural conversation. The server automatically:

  1. Stores messages when Claude calls memory_store_message

  2. Extracts entities (people, organizations, locations) from message content

  3. Detects preferences from statements like "I love Italian food"

  4. Builds a knowledge graph linking entities with typed relationships

Try a conversation like:

I’m a software engineer at Acme Corp. I work with Python and React. I love Italian food, especially pasta. My favorite restaurant is Bella Italia on Main Street. Next week I have a meeting with Sarah about the new authentication feature.

Step 6: Verify in Neo4j Browser

Open http://localhost:7474 and run:

MATCH (n) RETURN n LIMIT 50

You should see:

  • Conversation and Message nodes (your chat messages)

  • Entity nodes (Acme Corp, Bella Italia, Sarah, Main Street)

  • Preference nodes (Italian food, pasta)

  • MENTIONS relationships linking messages to entities

To see just the entities:

MATCH (e:Entity) RETURN e.name, e.type, e.description

Step 7: Test Memory Recall

In Claude Desktop, ask:

Where do I like to eat?

Claude will call memory_search and find your stored preference for Italian food and Bella Italia.

Tell me about Sarah

Claude will call memory_get_entity (if using extended profile) or memory_search to find the entity and any related context.

Programmatic Server Usage

You can also start the MCP server from Python code:

from neo4j_agent_memory import MemoryClient, MemorySettings

settings = MemorySettings(
    neo4j={"uri": "bolt://localhost:7687", "password": "test-password"}
)

# Use MemoryIntegration for simplified memory operations
from neo4j_agent_memory import MemoryIntegration

memory = MemoryIntegration(
    neo4j_uri="bolt://localhost:7687",
    neo4j_password="test-password",
    session_strategy="per_day",
)

Next Steps

Tool Profiles

By default, the server starts with the extended profile (16 tools). For simpler use cases or to reduce context overhead, use the core profile:

{
  "mcpServers": {
    "neo4j-agent-memory": {
      "command": "neo4j-agent-memory",
      "args": ["mcp", "serve",
               "--password", "test-password",
               "--profile", "core"]
    }
  }
}

See the MCP Tools Reference for the complete list of tools in each profile.