Claude × Neo4j MCP Guide | Query Knowledge Graphs in Natural Language

Why Combine Claude with Neo4j?

Traditionally, accessing data in Neo4j required learning Cypher, a dedicated query language. Even a simple operation like "list all friends-of-friends reachable from a specific person" required writing precise MATCH patterns.

Claude integration dramatically lowers this barrier. Simply type "Show me everyone connected to Yamada-san within 2 degrees" in natural language, and Claude generates the appropriate Cypher, sends it to Neo4j, and returns the results in plain text. The biggest benefit is that business users beyond data scientists can now take advantage of graph analysis.

What Is MCP (Model Context Protocol)?

MCP is an open connectivity standard developed by Anthropic that gives Claude access to external tools and data sources. It follows a server-client model: the tool provider runs an "MCP server," and the "MCP client" on the Claude side calls it.

For Neo4j, once you start the official MCP server package, Claude Desktop automatically recognizes the database connection tools. After connecting, Claude can autonomously perform operations such as:

• Searching for nodes and relationships in the graph
• Adding new nodes and relationships
• Updating and deleting existing data
• Retrieving schema information

Setting Up the Neo4j MCP Server

Prerequisites: Node.js (v18 or later) and npm must be installed, and a Neo4j Desktop or Neo4j AuraDB instance must be running.

1. Open a terminal and run npm install -g @neo4j/mcp-server to install the server package.
2. Prepare your Neo4j connection details (URL, username, password). Defaults are bolt://localhost:7687 / neo4j / your configured password.
3. Set the three environment variables: NEO4J_URI, NEO4J_USER, and NEO4J_PASSWORD.
4. Start the server with the neo4j-mcp-server command. If you see a message like MCP server listening on port 3000, the setup is successful.

While the server is running, Claude Desktop can read from and write to the database through this MCP endpoint.

Connecting Claude Desktop to Neo4j

Open Claude Desktop's configuration file (on macOS: ~/Library/Application Support/Claude/claude_desktop_config.json) and add the following to the mcpServers section:

{
  "mcpServers": {
    "neo4j": {
      "command": "neo4j-mcp-server",
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "your-password"
      }
    }
  }
}

Save the configuration and restart Claude Desktop. An icon indicating that the Neo4j tool is available should appear near the chat input area. If it doesn't appear, check for JSON syntax errors in the configuration file or verify that the MCP server is running.

Auto-Generating Cypher Queries from Natural Language

Once connected, try querying in natural language. For example, using the sample database bundled with Neo4j (the movies graph containing relationships between movies, actors, and directors), you can have conversations like these:

Input Example 1: "Show me all the movies Tom Hanks appeared in."

Claude internally generates the Cypher MATCH (p:Person {name:'Tom Hanks'})-[:ACTED_IN]->(m:Movie) RETURN m.title and returns the results in natural language.

Input Example 2: "List the directors of action movies released after 2000."

Even when more complex filtering is needed, Claude references the schema information and constructs the appropriate query. You can ask "What Cypher did you run?" to see the query itself, making it useful for learning purposes as well.

Thomas Rehmer's explanatory article published on Medium (reference: medium.com/@thomasrehmer/claude-neo4j-with-mcp...) also notes that this natural language interface represents a "democratization of graph databases."

Practical Example: Building a Knowledge Graph

Via MCP, you can write data as well as read it. Here is a walkthrough using a "project management knowledge graph" as an example:

1. Instruct Claude: "Create nodes for Project A and team member Taro Yamada, and connect them with a 'responsible for' relationship."
2. Claude generates a CREATE statement and writes it to Neo4j.
3. Follow up: "Add GitHub and Slack as tools used by Yamada-san."
4. Claude generates and executes Cypher to add the nodes and create the relationships.
5. Finally, ask "List all elements involved in this project in a way that shows the full picture," and Claude will organize all nodes and relationships as text.

The ability to grow the graph through conversation is a major advantage — business stakeholders with rich domain knowledge can directly participate in building the knowledge graph.

Use Case Scenarios

Here are some use cases where this combination particularly shines:

Internal FAQ and document search: Store people, departments, documents, and keywords as nodes, then search the relationship graph in natural language to find "who knows about Project X."

Supply chain analysis: Map suppliers, products, and logistics routes as a graph, then ask "List all product lines that use this component."

Fraud detection prototype: Map relationships between transactions, accounts, and IP addresses as a graph, then investigate unusual connection patterns in natural language.

Codebase dependency visualization: Load a dependency graph of files, functions, and libraries into Neo4j, then ask "Show me all modules affected if I change this function."

Important Considerations

Permission management: Credentials passed to the MCP server often include write permissions. It is strongly recommended to create a read-only user for production database connections and use a separate user configuration for write operations.

Token consumption: Asking questions that retrieve all records from a large graph can produce a huge amount of text, putting pressure on Claude's context window. Instruct Claude to include a LIMIT clause in its queries, or embed the restriction in a system prompt in advance.

Sharing schema in advance: To help Claude generate more accurate Cypher, it is effective to share the graph's node labels, properties, and relationship types upfront. A common approach is to provide the output of CALL db.schema.visualization() at the start of a session.

Version compatibility: The Neo4j MCP server is actively under development, so behavior may vary depending on the package version. It is recommended to check the release notes of the official repository (github.com/neo4j-labs/mcp-neo4j) before installing.

Summary

By connecting Claude and Neo4j via MCP, you can work with a graph database without learning Cypher. Setup requires only adding a few lines to a JSON file and starting the MCP server — the barrier to entry is low. Since knowledge graphs can be built, queried, and updated entirely in natural language, team members beyond data engineers can participate in graph analysis. Start by verifying the behavior with the sample movies graph, then consider applying it to your own domain.