Skip to main content
← Back to Articles
mcpcursorneo4jgraph-databasecypheraurasetup2026

Neo4j MCP Server Cursor IDE Setup 2026

Neo4j MCP server Cursor IDE setup 2026: connect Cursor to Neo4j with the official neo4j-mcp server (uvx, Homebrew or binary) or the hosted MCP for Aura URL, the exact mcp.json, read-only mode and tool filtering, the APOC requirement, and fixes for handshake errors.

By Web MCP Guide•November 14, 2026•12 min read

How do you connect Neo4j to Cursor with MCP? Add Neo4j's official server, neo4j-mcp, to ~/.cursor/mcp.json (or .cursor/mcp.json in a project). For a self-hosted database, run it over stdio with uvx neo4j-mcp-server and four required environment variables: NEO4J_MCP_URI, NEO4J_MCP_USERNAME, NEO4J_MCP_PASSWORD and NEO4J_MCP_DATABASE. For an Aura instance, skip the local install and point Cursor at the hosted URL https://<instance-id>.mcp-instances.neo4j.io after turning on tool authentication in the Aura console. Either way, the database needs the APOC plugin, and you should start with NEO4J_MCP_READ_ONLY=true.

Once it is connected, Cursor's agent can read your graph schema, run read-only Cypher, and (if you allow it) run write queries, all from the chat while you work on the code that talks to the database.

New to MCP? Read what the Model Context Protocol is first, then come back.

Which Neo4j MCP server should you use?

There are two projects with "Neo4j MCP" in the name, and search results mix them up.

Official neo4j/mcpNeo4j Labs neo4j-contrib/mcp-neo4j
Who supports itNeo4j product team, with versioned docs at neo4j.com/docs/mcpNeo4j Field GenAI team as a Labs project, no SLAs or backward-compatibility guarantees
What it isOne server: schema, read Cypher, write Cypher, GDS procedure listSeveral servers: mcp-neo4j-cypher, mcp-neo4j-memory, mcp-neo4j-cloud-aura-api, mcp-neo4j-data-modeling
Installuvx neo4j-mcp-server, brew install neo4j-mcp, or a release binaryPer-server packages (see each README)
Hosted optionMCP for Aura (one URL per instance)No

The Labs README now points readers to the official server for product use. This guide covers the official server. If you want an agent that stores long-term "memory" as a graph, the Labs mcp-neo4j-memory server is a different tool for a different job; our general memory MCP server guide covers that pattern.

What the official server exposes

Neo4j documents four tools:

  • get-schema: introspects node labels, relationship types and property keys. This is what lets the agent write Cypher against your real model instead of guessing.

  • read-cypher: runs Cypher in read mode. It rejects writes, schema and admin operations, and PROFILE queries. Neo4j enforces this with an extra round-trip that checks the query type, and notes that a custom procedure wrongly classified as read-only could slip past it.

  • write-cypher: runs arbitrary write Cypher. Neo4j's own warning is that LLM-generated queries can cause harm and this tool belongs in development environments.

  • list-gds-procedures: lists Graph Data Science procedures. It only appears if the GDS library is installed.
  • Useful prompts once it is running:

  • "What labels and relationship types are in this database, and which properties does :Customer have?"

  • "Write a Cypher query for the five products most often bought together with product 123, then run it."

  • "Our OrderRepository.findByCustomer is slow. Look at the schema and tell me which index is missing."
  • Before you start

    You need three things:

    1. A Neo4j database with APOC. The server checks for the APOC plugin, including its meta component, during the MCP handshake. Without it, the connection fails. Aura instances ship with APOC Core; on a self-managed server, install it from the APOC docs.
    2. A user for the agent. Neo4j's security page recommends a restricted Neo4j user for exploring the database and reviewing generated Cypher before running it, especially on production. Do not hand the agent the neo4j admin account on anything that matters.
    3. A way to run the server, depending on the route you pick below: uv (for uvx), Homebrew, or the downloaded binary. The hosted Aura route needs none of these.

    Option 1: Self-hosted Neo4j over stdio (uvx)

    This is the quickest route for a local database, a Docker container or a self-managed server. Install uv so uvx is on your PATH. Then open ~/.cursor/mcp.json for all projects, or .cursor/mcp.json for one repo, and add:

    {
      "mcpServers": {
        "neo4j-mcp": {
          "command": "uvx",
          "args": ["neo4j-mcp-server"],
          "env": {
            "NEO4J_MCP_URI": "bolt://localhost:7687",
            "NEO4J_MCP_USERNAME": "neo4j",
            "NEO4J_MCP_PASSWORD": "password",
            "NEO4J_MCP_DATABASE": "neo4j",
            "NEO4J_MCP_READ_ONLY": "true",
            "NEO4J_MCP_TELEMETRY": "false"
          }
        }
      }
    }
    

    uvx downloads the server from PyPI the first time it runs; there is no separate install step. Replace the URI, user, password and database with your own. Neo4j's docs make all four of the first variables mandatory in stdio mode, including the database name, so do not leave NEO4J_MCP_DATABASE out even if you only have one.

    Save the file, open Cursor Settings > Tools & MCP, and check that neo4j-mcp shows a green status with its tools listed. If it does not, jump to troubleshooting below.

    Using Homebrew or the binary instead

    If you would rather not run through uvx, install the executable with brew install neo4j-mcp, or download the archive for your OS from the GitHub releases page and put neo4j-mcp on your PATH (neo4j-mcp -v should print a version). Then change two lines in the config:

    "command": "neo4j-mcp",
    

    and remove the args line. The env block stays the same. On Windows, put neo4j-mcp.exe in a folder such as %LOCALAPPDATA%\Programs\neo4j-mcp, add that folder to your user PATH and restart Cursor so it sees the change.

    Option 2: Neo4j Aura with the hosted MCP URL

    Neo4j runs MCP for Aura, a hosted MCP server for each Aura instance. Neo4j's docs say it is available on Free, Professional and Business Critical tiers, with Virtual Dedicated Cloud support coming later. There is nothing to install locally.

    1. In the Aura console, open your organization from the top bar, go to Security, and enable Tool authentication with Aura user.
    2. Find your instance ID under Instances, or open the instance's [...] menu, choose Inspect, and copy the MCP server URL. Do not confuse it with the connection URI or the Query API URL; they are different.
    3. Add it to Cursor:

    {
      "mcpServers": {
        "neo4j-mcp": {
          "url": "https://<instance-id>.mcp-instances.neo4j.io"
        }
      }
    }
    

    Authentication runs through your Aura user (that is what the tool authentication setting turns on), so there is no database password in this file. If Cursor shows a sign-in prompt on first connect, complete it, then check for a green status under Settings > Tools & MCP.

    > Wiring Neo4j into a production agent, not just your editor? That usually means a dedicated database user, read-only defaults, HTTP mode behind TLS and a decision about who can call write-cypher. If you want help designing it for your stack, talk to us.

    Lock it down: read-only mode and tool filtering

    Start every new connection with NEO4J_MCP_READ_ONLY=true. In read-only mode write-cypher is not exposed to Cursor at all, so the agent cannot create, merge, set or delete anything, even if you ask it to by accident. Turn it off only on a development database, and only while you need it.

    You can also trim the tool list with NEO4J_MCP_TOOLS, a comma-separated list such as get-schema,read-cypher. Two rules from Neo4j's docs matter here: filters can only narrow the tool set, never widen it, and read-only mode wins over an explicit tool list, so listing write-cypher while read-only is on does not bring it back.

    A few other settings worth knowing:

    VariableWhat it doesDefault
    NEO4J_MCP_SCHEMA_SAMPLE_SIZENodes sampled to infer the schema100
    NEO4J_MCP_REQUEST_TIMEOUTMax time per MCP request, e.g. 45s or 5m3m (max 30m)
    NEO4J_MCP_LOG_LEVELLogging verbosityinfo
    NEO4J_MCP_TELEMETRYAnonymous usage data (tools used, OS, CPU architecture)true

    If your graph has many labels that appear only on rare nodes, a sample of 100 can miss them. Raise the sample size if get-schema keeps leaving out parts of your model, and raise the timeout if long analytical reads time out.

    Keep the password out of your repo

    The stdio config holds a database password. If you put it in a project-level .cursor/mcp.json, add that file to .gitignore or keep the Neo4j entry in your user-level ~/.cursor/mcp.json instead. Our guide on authenticating MCP servers with OAuth and API keys covers patterns for loading secrets from the environment rather than hardcoding them. The hosted Aura route avoids the problem because the config holds only a URL.

    HTTP mode for shared or remote setups

    The stdio setup starts one server per Cursor window, which is right for most individual developers. The server also has an HTTP mode (NEO4J_MCP_TRANSPORT_MODE=http) meant for shared, multi-tenant deployments. In HTTP mode you do not set the URI, user, password or database on the server. Credentials arrive per request in a header (by default Authorization), and the database is chosen by the URL path, /db/{databaseName}/mcp. The server binds to 127.0.0.1 by default, and TLS is off unless you enable it with a certificate and key. Requests can narrow the tools further with the X-Neo4j-MCP-Tools or X-Neo4j-MCP-ReadOnly: true headers, but cannot add tools the server was not started with.

    Troubleshooting

    The server shows red or "failed to connect" in Cursor. In stdio mode, the server checks connectivity, query execution and APOC when Cursor sends the MCP handshake, not when the process starts. An unreachable database, a bad password, a wrong database name or missing APOC all fail at that point with an error message. Check Cursor's MCP logs for the text, then test the same URI and credentials in Neo4j Browser or cypher-shell.

    The error mentions APOC or the meta component. Install APOC on the server and make sure the meta procedures are included. On Neo4j 5.26.18 specifically, Neo4j lists a known APOC bug that breaks get-schema; upgrade to 5.26.19 or later.

    uvx: command not found. Cursor launches the server with its own environment. Install uv, restart Cursor, or put the absolute path to uvx in command. The same applies to neo4j-mcp if Homebrew installed it outside the PATH Cursor sees.

    list-gds-procedures is missing. That is expected when Graph Data Science is not installed. The other three tools still work. If you explicitly list list-gds-procedures in NEO4J_MCP_TOOLS and GDS is missing, the tool list request returns an error instead.

    The agent says a query is "not read-only" when it looks harmless. read-cypher also rejects SHOW admin commands, schema commands such as CREATE INDEX, and PROFILE queries. That is by design. Run them yourself, or on a dev database switch read-only off for that session.

    Aura connection asks you to sign in every time, or fails. Confirm tool authentication is enabled at the organization level in Security, and that you copied the MCP URL from Inspect, not the neo4j+s:// connection URI.

    For general MCP connection problems, see how to debug MCP server issues. If you also work with relational data, our Postgres MCP server setup guide uses the same read-only-first approach.

    Frequently asked questions

    Is there an official Neo4j MCP server?

    Yes. Neo4j publishes it on GitHub as neo4j/mcp, with documentation at neo4j.com/docs/mcp. You can run it with uvx neo4j-mcp-server, install it with brew install neo4j-mcp, download a release binary, or use the hosted MCP for Aura URL for an Aura instance.

    Does the Neo4j MCP server need APOC?

    Yes. During the MCP handshake the server checks that it can connect, that it can run queries, and that the APOC plugin with its meta component is present. If APOC is missing, the connection fails with an error.

    How do I stop Cursor from writing to my Neo4j database?

    Set NEO4J_MCP_READ_ONLY to true. The write-cypher tool is then not exposed to the client at all, and read-only mode takes precedence over any tool list you set with NEO4J_MCP_TOOLS. Using a restricted Neo4j user adds a second layer.

    Can I use the Neo4j MCP server with Aura Free?

    Neo4j's docs list MCP for Aura as available for Free, Professional and Business Critical tier instances. You enable tool authentication in the Aura console's Security settings, then add your instance's MCP URL to Cursor.

    What is the difference between neo4j/mcp and mcp-neo4j-cypher?

    neo4j/mcp is the official, product-supported server. mcp-neo4j-cypher is one of several Neo4j Labs servers in the neo4j-contrib/mcp-neo4j repository; Labs projects are actively developed but carry no SLAs or backward-compatibility guarantees, and the Labs README points to the official server for product use.

    Related Guides


  • Cursor IDE MCP Setup Guide

  • MCP Server for Postgres Setup Guide

  • How to Authenticate MCP Servers: OAuth and API Keys

  • MCP Security Best Practices (2026)
  • Sources: neo4j/mcp README, Neo4j MCP docs: Installation, Client configuration, STDIO and HTTP configuration, Tools, Requirement checks, Security, MCP for Aura, Telemetry, Known issues, neo4j-contrib/mcp-neo4j README, Cursor MCP documentation. Checked November 14, 2026.




    Related guides