neo4j_mcp.md

title	Neo4j using MCP
type	docs
weight	2
description	Connect your IDE to Neo4j using Toolbox.

Model Context Protocol (MCP) is an open protocol for connecting Large Language Models (LLMs) to data sources like Neo4j. This guide covers how to use MCP Toolbox for Databases to expose your developer assistant tools to a Neo4j instance:

• Cursor
• Windsurf (Codium)
• Visual Studio Code (Copilot)
• Cline (VS Code extension)
• Claude desktop
• Claude code
• Gemini CLI
• Gemini Code Assist

Set up the database

1. Create or select a Neo4j instance.

Install MCP Toolbox

1. Download the latest version of Toolbox as a binary. Select the correct binary corresponding to your OS and CPU architecture. You are required to use Toolbox version v0.15.0+:

   {{< tabpane persist=header >}} {{< tab header="linux/amd64" lang="bash" >}} curl -O https://storage.googleapis.com/genai-toolbox/v0.32.0/linux/amd64/toolbox {{< /tab >}}

{{< tab header="darwin/arm64" lang="bash" >}} curl -O https://storage.googleapis.com/genai-toolbox/v0.32.0/darwin/arm64/toolbox {{< /tab >}}

{{< tab header="darwin/amd64" lang="bash" >}} curl -O https://storage.googleapis.com/genai-toolbox/v0.32.0/darwin/amd64/toolbox {{< /tab >}}

{{< tab header="windows/amd64" lang="bash" >}} curl -O https://storage.googleapis.com/genai-toolbox/v0.32.0/windows/amd64/toolbox.exe {{< /tab >}} {{< /tabpane >}}

1. Make the binary executable:

   chmod +x toolbox

2. Verify the installation:

   ./toolbox --version

Configure your MCP Client

{{< tabpane text=true >}} {{% tab header="Claude code" lang="en" %}}

1. Install Claude Code.

2. Create a .mcp.json file in your project root if it doesn't exist.

3. Add the following configuration, replace the environment variables with your values, and save:

   {
     "mcpServers": {
       "neo4j": {
         "command": "./PATH/TO/toolbox",
         "args": ["--prebuilt","neo4j","--stdio"],
         "env": {
           "NEO4J_URI": "",
           "NEO4J_DATABASE": "",
           "NEO4J_USERNAME": "",
           "NEO4J_PASSWORD": ""
         }
       }
     }
   }

4. Restart Claude code to apply the new configuration. {{% /tab %}} {{% tab header="Claude desktop" lang="en" %}}

5. Open Claude desktop and navigate to Settings.

6. Under the Developer tab, tap Edit Config to open the configuration file.

7. Add the following configuration, replace the environment variables with your values, and save:

   {
     "mcpServers": {
       "neo4j": {
         "command": "./PATH/TO/toolbox",
         "args": ["--prebuilt","neo4j","--stdio"],
         "env": {
           "NEO4J_URI": "",
           "NEO4J_DATABASE": "",
           "NEO4J_USERNAME": "",
           "NEO4J_PASSWORD": ""
         }
       }
     }
   }

8. Restart Claude desktop.

9. From the new chat screen, you should see a hammer (MCP) icon appear with the new MCP server available. {{% /tab %}} {{% tab header="Cline" lang="en" %}}

10. Open the Cline extension in VS Code and tap the MCP Servers icon.

11. Tap Configure MCP Servers to open the configuration file.

12. Add the following configuration, replace the environment variables with your values, and save:

    {
      "mcpServers": {
        "neo4j": {
          "command": "./PATH/TO/toolbox",
          "args": ["--prebuilt","neo4j","--stdio"],
          "env": {
            "NEO4J_URI": "",
            "NEO4J_DATABASE": "",
            "NEO4J_USERNAME": "",
            "NEO4J_PASSWORD": ""
          }
        }
      }
    }

13. You should see a green active status after the server is successfully connected. {{% /tab %}} {{% tab header="Cursor" lang="en" %}}

14. Create a .cursor directory in your project root if it doesn't exist.

15. Create a .cursor/mcp.json file if it doesn't exist and open it.

16. Add the following configuration, replace the environment variables with your values, and save:

    {
      "mcpServers": {
        "neo4j": {
          "command": "./PATH/TO/toolbox",
          "args": ["--prebuilt","neo4j","--stdio"],
          "env": {
            "NEO4J_URI": "",
            "NEO4J_DATABASE": "",
            "NEO4J_USERNAME": "",
            "NEO4J_PASSWORD": ""
          }
        }
      }
    }

17. Open Cursor and navigate to Settings > Cursor Settings > MCP. You should see a green active status after the server is successfully connected. {{% /tab %}} {{% tab header="Visual Studio Code (Copilot)" lang="en" %}}

18. Open VS Code and create a .vscode directory in your project root if it doesn't exist.

19. Create a .vscode/mcp.json file if it doesn't exist and open it.

20. Add the following configuration, replace the environment variables with your values, and save:

    {
    "mcp" : {
        "servers": {
        "neo4j": {
            "command": "./PATH/TO/toolbox",
            "args": ["--prebuilt","neo4j","--stdio"],
            "env": {
              "NEO4J_URI": "",
              "NEO4J_DATABASE": "",
              "NEO4J_USERNAME": "",
              "NEO4J_PASSWORD": ""
            }
         }
        }
      }
    }

{{% /tab %}} {{% tab header="Windsurf" lang="en" %}}

1. Open Windsurf and navigate to the Cascade assistant.

2. Tap on the hammer (MCP) icon, then Configure to open the configuration file.

3. Add the following configuration, replace the environment variables with your values, and save:

   {
     "mcpServers": {
       "neo4j": {
         "command": "./PATH/TO/toolbox",
         "args": ["--prebuilt","neo4j","--stdio"],
         "env": {
           "NEO4J_URI": "",
           "NEO4J_DATABASE": "",
           "NEO4J_USERNAME": "",
           "NEO4J_PASSWORD": ""
         }
       }
     }
   }

{{% /tab %}} {{% tab header="Gemini CLI" lang="en" %}}

1. Install the Gemini CLI.

2. In your working directory, create a folder named .gemini. Within it, create a settings.json file.

3. Add the following configuration, replace the environment variables with your values, and then save:

   {
     "mcpServers": {
       "neo4j": {
         "command": "./PATH/TO/toolbox",
         "args": ["--prebuilt","neo4j","--stdio"],
         "env": {
           "NEO4J_URI": "",
           "NEO4J_DATABASE": "",
           "NEO4J_USERNAME": "",
           "NEO4J_PASSWORD": ""
         }
       }
     }
   }

{{% /tab %}} {{% tab header="Gemini Code Assist" lang="en" %}}

1. Install the Gemini Code Assist extension in Visual Studio Code.

2. Enable Agent Mode in Gemini Code Assist chat.

3. In your working directory, create a folder named .gemini. Within it, create a settings.json file.

4. Add the following configuration, replace the environment variables with your values, and then save:

   {
     "mcpServers": {
       "neo4j": {
         "command": "./PATH/TO/toolbox",
         "args": ["--prebuilt","neo4j","--stdio"],
         "env": {
           "NEO4J_URI": "",
           "NEO4J_DATABASE": "",
           "NEO4J_USERNAME": "",
           "NEO4J_PASSWORD": ""
         }
       }
     }
   }

{{% /tab %}} {{< /tabpane >}}

Use Tools

Your AI tool is now connected to Neo4j using MCP. Try asking your AI assistant to get the graph schema or execute Cypher statements.

The following tools are available to the LLM:

1. get_schema: extracts the complete database schema, including details about node labels, relationships, properties, constraints, and indexes.
2. execute_cypher: executes any arbitrary Cypher statement.

{{< notice note >}} Prebuilt tools are pre-1.0, so expect some tool changes between versions. LLMs will adapt to the tools available, so this shouldn't affect most users. {{< /notice >}}