How to add Neo4j Cypher MCP Server to Windsurf

Run Cypher queries and explore graph schema on Neo4j from your AI assistant. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 15, 2026 · 1.3k★ · stdio · apikey · official

Windsurf config for Neo4j Cypher MCP Server

uvx mcp-neo4j-cypher --transport stdio

{
  "mcpServers": {
    "neo4j-cypher-mcp-server": {
      "command": "uvx",
      "args": [
        "mcp-neo4j-cypher",
        "--transport",
        "stdio"
      ],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_DATABASE": "neo4j",
        "NEO4J_PASSWORD": "<your-password>",
        "NEO4J_USERNAME": "neo4j"
      }
    }
  }
}

Requires `uv` (the Python package runner). Install it from https://docs.astral.sh/uv/ if `uvx` is not found.

Setup steps

1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
2Paste the Neo4j Cypher MCP Server config below.
3Fill in placeholder secrets, then save.
4Click Refresh in the MCP panel.
5Neo4j Cypher MCP Server's tools become available to Cascade.

Before you start

Python with the uv/uvx package manager (run via `uvx mcp-neo4j-cypher`)
A running Neo4j instance (Neo4j Aura or self-managed), reachable over Bolt
Neo4j connection details: NEO4J_URI (default bolt://localhost:7687), NEO4J_USERNAME, NEO4J_PASSWORD, NEO4J_DATABASE (default neo4j)
The APOC plugin installed and enabled — required for the schema-inspection tool
An MCP-capable client such as Claude Desktop or Cursor

What Neo4j Cypher MCP Server can do in Windsurf

get_neo4j_schema

List all node labels with their properties (name and type) and relationships to other node types (requires APOC)

read_neo4j_cypher

Execute a read-only Cypher query and return the results

write_neo4j_cypher

Execute an updating Cypher query and return an operation summary (disabled in read-only mode)

Security

The server can execute write Cypher, so use a least-privilege Neo4j user if the agent should not mutate the graph. Credentials are passed via env vars, so prefer a dedicated account over the admin user.

Neo4j Cypher MCP Server + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the Neo4j Cypher MCP Server config there under the "mcpServers" key and restart the client.

Is Neo4j Cypher MCP Server safe to use with Windsurf?

How do I authenticate to Neo4j?

Provide standard Bolt credentials via environment variables: NEO4J_URI, NEO4J_USERNAME, and NEO4J_PASSWORD (plus NEO4J_DATABASE to target a specific database). This works for both Aura and self-managed instances.

Why do I get no schema / a schema error?

The `get_neo4j_schema` tool depends on the APOC plugin. Install and enable APOC on your Neo4j instance, then retry.

Can I prevent the model from writing to my graph?

Yes. Start the server with `--read-only` or set NEO4J_READ_ONLY=true to disable `write_neo4j_cypher` entirely, leaving only schema and read tools.

View repo Full Neo4j Cypher MCP Server page