neo4j-contrib/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.
Install
| Harness | Tools (MCP) | Skill | Guide |
| --------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | ------------------------------------ |
| **Claude Code** | /plugin marketplace add neo4j-contrib/gds-agent → /plugin install gds-agent@neo4j-gds | bundled with the plugin | setup |
| **Claude Desktop** | download the .mcpb from releases, double-click | upload the skill zip in Settings → Skills | setup |
| **OpenAI Codex** | codex mcp add neo4j-gds -- uvx gds-agent | npx skills add neo4j-contrib/gds-agent -a codex | setup |
| **Cursor** | one-click badge | npx skills add neo4j-contrib/gds-agent -a cursor | setup |
| **VS Code / Copilot** | one-click badge or .vscode/mcp.json | npx skills add neo4j-contrib/gds-agent -a copilot | setup |
| **Gemini CLI** | gemini extensions install https://github.com/neo4j-contrib/gds-agent | bundled with the extension | setup |
| **Your own agent** | any MCP client (stdio/HTTP) | inject SKILL.md as instructions | setup |
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):
| Variable | Required | Purpose |
| ------------------------------------------------------ | ------------ | --------------------------------------------------- |
| NEO4J_URI | yes | neo4j:// or neo4j+s:// connection URI |
| NEO4J_USERNAME / NEO4J_PASSWORD | yes | database credentials |
| NEO4J_DATABASE | no | database name (defaults to neo4j) |
| AURA_API_CLIENT_ID / AURA_API_CLIENT_SECRET | session mode | Aura API credentials for Aura Graph Analytics |
| AURA_API_PROJECT_ID | no | only if the API client can access multiple projects |
| SESSION_MEMORY_GB / SESSION_TTL_HOURS | no | session defaults (8 GB / 12 h) |
| SESSION_TIMEOUT_SECONDS | no | seconds to wait for a session to become Ready |
| GDS_AGENT_MAX_RESULT_ROWS / _CHARS / _CELL_CHARS | no | tool output limits (500 / 100000 / 200) |
By default the server uses STDIO transport for local MCP clients. For HTTP-native clients, run the server with streamable HTTP:
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.