Neo4j GDS Agent

GDS Agent

The GDS Agent let LLMs reason and do data science work on your graph data in Neo4j, by using two artifacts:

• Tools — an MCP server exposing Neo4j Graph Data Science (GDS) algorithms: centrality, community detection, path finding, similarity, node embeddings, and ML pipelines.
• Skills — an agent skill (neo4j-graph-data-scientist) teaching the agent how and when to use those tools and best practices for doing data science on graphs.

It works with any MCP-capable harness — Claude Code, Claude Desktop, claude.ai, OpenAI Codex, Cursor, VS Code/Copilot, Gemini CLI — and programmatically from agent frameworks. It uses the GDS plugin on self-managed Neo4j and GDS Aura Graph Analytics sessions on AuraDB, over STDIO or HTTP transport.

Once set up, you can ask any graph question about your Neo4j graph and get answers. You can collaborate with the agent as a graph data scientist to solve complex tasks.

[gds-agent-arch]

Install

Most local setups need uv installed (the server runs via uvx gds-agent from PyPI). Generic MCP clients run uvx gds-agent over stdio with the environment variables below.

Configuration reference

Set as environment variables (or the credential form of your harness's installer):

By default the server uses STDIO transport for local MCP clients. For HTTP-native clients, run the server with streamable HTTP:

gds-agent --transport http --host 127.0.0.1 --port 8000 --path /mcp

The equivalent environment variables are GDS_AGENT_TRANSPORT, GDS_AGENT_HOST, GDS_AGENT_PORT, and GDS_AGENT_PATH. The Neo4j MCP-style NEO4J_TRANSPORT and NEO4J_MCP_SERVER_* names are also supported.

GDS Aura Graph Analytics (sessions)

The server detects whether the connected Neo4j has the GDS plugin installed or whether to use a GDS Aura Graph Analytics session. Detection runs gds.session.list() on startup; if it succeeds, session mode is used and graph projections fall back to gds.graph.project.remote.

Session mode requires Aura API credentials (see the configuration reference above) in the same .env file or env block as the database credentials. Sessions are managed explicitly by the agent: three extra tools become available in session mode (list_sessions, create_session, and delete_session). A session must first be created with create_session, project_graph_cypher then projects each graph into the session named by its required sessionName parameter, and algorithm calls are routed to the right session automatically by graphName. Most workflows need a single session holding all graphs; multiple sessions allow running analyses in parallel. To resize a session (e.g. after an OOM), delete it and create it again with a larger memoryGB. All sessions created by the server are named with an mcp_ prefix. Aura sessions are charged separate to the DB.

The skill

[skills/neo4j-graph-data-scientist](skills/neo4j-graph-data-scientist/SKILL.md) is consumed from this one location by the Claude Code plugin, the Gemini extension, npx skills, and the release skill zip. It covers GDS-specific workflow best practices with a troubleshooting reference guide, as well as general data science best practices. It is designed for the gds-agent and mcp-neo4j-cypher MCP servers.

Read-only Cypher alongside GDS

The GDS server deliberately executes no arbitrary Cypher — its only Cypher entry point is graph projection. To let the agent also read the underlying data (inspect properties, aggregate, verify algorithm results), pair it with the [mcp-neo4j-cypher](https://github.com/neo4j-contrib/mcp-neo4j) server in read-only mode.

The Claude Code plugin and the Gemini CLI extension already bundle it: one install configures both servers with the same credentials, and NEO4J_READ_ONLY=true removes its write tool. NEO4J_RESPONSE_TOKEN_LIMIT caps read-query responses (tokens) so large results don’t overwhelm the model; omit it for no Cypher-side limit. On any other harness, register a second server alongside gds-agent:

"neo4j-cypher": {  "command": "uvx",  "args": ["[email protected]", "--transport", "stdio"],  "env": {    "NEO4J_URI": "neo4j://localhost:7687",    "NEO4J_USERNAME": "neo4j",    "NEO4J_PASSWORD": "<your-password>",    "NEO4J_READ_ONLY": "true",    "NEO4J_RESPONSE_TOKEN_LIMIT": "20000"  }}

Example dataset

To load a London underground example dataset:

1. Fork and clone the repository
2. Install the Neo4j database with GDS plugin: Download the Neo4j Desktop from Neo4j Download Center Install the GDS plugin from the Neo4j Desktop Create a new database and start it
3. Populate .env file with necessary credentials:

 NEO4J_URI=bolt://localhost:7687  # or your database URI NEO4J_USERNAME=neo4j  # or your db username NEO4J_PASSWORD=your_password

4. Load the London Underground dataset with the following command (uv resolves the script's dependencies automatically):

 uv run import_data.py --undirected

Connect to your DB and querying the graph from Neo4j workspace, you should see: London Underground Graph

Start the server for dev

1. When inside the /mcp_server directory, run uv sync --dev and run uv run gds-agent to start the MCP server standalone, or run claude to start claude-cli with the agent.
2. To try the plugin (MCP server + skill) from your working tree: claude --plugin-dir . from the repository root.

Releases

Version numbers are kept in lockstep across pyproject.toml and all distribution manifests by scripts/bump_version.py. Pushing a v* tag triggers the release workflow.

How to contribute

Open a pull request from a branch of your forked repository into the main branch of this repo, for example mygithubid:add-new-algo -> neo4j-contrib:main.

The CI build in github action requires all codestyle checks and tests to pass.

To run and fix codestyle checks locally, in the /mcp_server directory, run:

uv sync --dev

to setup the python environment. And then,

uv run pytest tests -v -suv run ruff checkuv run ruff format

for all tests and codestyle fixes.

Feature request and bug reports

To report a bug or a new feature request, raise an issue. If it is a bug, include the full stacktrace and errors. When available, attach relevant logs in mcp_server_neo4j_gds.log. This file is located inside the /mcp_server/src_mcp_server_neo4j_gds directory if the gds agent is running from source, or inside the logging path for Claude (e.g /Library/Logs/Claude for Claude Desktop on Mac). Include relevant minimal dataset that can be used to reproduce the issue if possible.

Additional resources

The GDS agent can be used with other MCP servers, such as those that provide additional Neo4j toolings: https://github.com/neo4j-contrib/mcp-neo4j Arxiv paper including details about the architecture and benchmark results: https://arxiv.org/abs/2508.20637.