Skip to content
Back to search

gds-agent

Neo4j Graph Data Scientist Agent (MCP Server & Skills)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/neo4j-contrib/gds-agent with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/neo4j-contrib/gds-agent'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/neo4j-contrib--gds-agent/badge.svg)](/listings/neo4j-contrib--gds-agent)

HTML

<a href="/listings/neo4j-contrib--gds-agent"><img src="/api/listings/neo4j-contrib--gds-agent/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

| 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](doc/setup/claude-code.md) | | **Claude Desktop** | download the `.mcpb` from [releases](https://github.com/neo4j-contrib/gds-agent/releases), double-click | upload the skill zip in Settings → Skills | [setup](doc/setup/claude-desktop.md) | | **OpenAI Codex** | `codex mcp add neo4j-gds -- uvx gds-agent` | `npx skills add neo4j-contrib/gds-agent -a codex` | [setup](doc/setup/codex.md) | | **Cursor** | one-click badge | `npx skills add neo4j-contrib/gds-agent -a cursor` | [setup](doc/setup/cursor.md) | | **VS Code / Copilot** | one-click badge or `.vscode/mcp.json` | `npx skills add neo4j-contrib/gds-agent -a copilot` | [setup](doc/setup/vscode.md) | | **Gemini CLI** | `gemini extensions install https://github.com/neo4j-contrib/gds-agent` | bundled with the extension | [setup](doc/setup/gemini-cli.md) | | **Your own agent** | any MCP client (stdio/HTTP) | inject SKILL.md as instructions | [setup](doc/setup/programmatic.md) |

Most local setups need [uv](https://docs.astral.sh/uv/getting-started/installation/) 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:

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 19 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "neo4j-gds",
  3. "owner": {
  4. "name": "Neo4j",
  5. "url": "https://github.com/neo4j-contrib"
  6. },
  7. "metadata": {
  8. "description": "Neo4j Graph Data Science agent plugin: the gds-agent MCP server plus graph-analysis skills"
  9. },
  10. "plugins": [
  11. {
  12. "name": "gds-agent",
  13. "source": "./",
  14. "description": "Run graph algorithms (centrality, community detection, path finding, similarity, embeddings, ML pipelines) on any Neo4j database, with a graph-analysis skill that guides algorithm selection.",
  15. "category": "database",
  16. "tags": ["neo4j", "graph", "gds", "graph-data-science", "mcp"]
  17. }
  18. ]
  19. }
README.md · README · 138 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # GDS Agent
  2. The GDS Agent let LLMs reason and do data science work on your graph data in Neo4j, by using two artifacts:
  3. - **Tools** — an MCP server exposing Neo4j Graph Data Science (GDS) algorithms: centrality, community detection, path finding, similarity, node embeddings, and ML pipelines.
  4. - **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.
  5. 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.
  6. 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.
  7. ![gds-agent-arch](doc/gds-agent-arch.png)
  8. # Install
  9. | Harness | Tools (MCP) | Skill | Guide |
  10. | --------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | ------------------------------------ |
  11. | **Claude Code** | `/plugin marketplace add neo4j-contrib/gds-agent` → `/plugin install gds-agent@neo4j-gds` | bundled with the plugin | [setup](doc/setup/claude-code.md) |
  12. | **Claude Desktop** | download the `.mcpb` from [releases](https://github.com/neo4j-contrib/gds-agent/releases), double-click | upload the skill zip in Settings → Skills | [setup](doc/setup/claude-desktop.md) |
  13. | **OpenAI Codex** | `codex mcp add neo4j-gds -- uvx gds-agent` | `npx skills add neo4j-contrib/gds-agent -a codex` | [setup](doc/setup/codex.md) |
  14. | **Cursor** | one-click badge | `npx skills add neo4j-contrib/gds-agent -a cursor` | [setup](doc/setup/cursor.md) |
  15. | **VS Code / Copilot** | one-click badge or `.vscode/mcp.json` | `npx skills add neo4j-contrib/gds-agent -a copilot` | [setup](doc/setup/vscode.md) |
  16. | **Gemini CLI** | `gemini extensions install https://github.com/neo4j-contrib/gds-agent` | bundled with the extension | [setup](doc/setup/gemini-cli.md) |
  17. | **Your own agent** | any MCP client (stdio/HTTP) | inject SKILL.md as instructions | [setup](doc/setup/programmatic.md) |
  18. Most local setups need [uv](https://docs.astral.sh/uv/getting-started/installation/) installed (the server runs via `uvx gds-agent` from PyPI). Generic MCP clients run `uvx gds-agent` over stdio with the environment variables below.
  19. ## Configuration reference
  20. Set as environment variables (or the credential form of your harness's installer):
  21. | Variable | Required | Purpose |
  22. | ------------------------------------------------------ | ------------ | --------------------------------------------------- |
  23. | `NEO4J_URI` | yes | `neo4j://` or `neo4j+s://` connection URI |
  24. | `NEO4J_USERNAME` / `NEO4J_PASSWORD` | yes | database credentials |
  25. | `NEO4J_DATABASE` | no | database name (defaults to `neo4j`) |
  26. | `AURA_API_CLIENT_ID` / `AURA_API_CLIENT_SECRET` | session mode | Aura API credentials for Aura Graph Analytics |
  27. | `AURA_API_PROJECT_ID` | no | only if the API client can access multiple projects |
  28. | `SESSION_MEMORY_GB` / `SESSION_TTL_HOURS` | no | session defaults (8 GB / 12 h) |
  29. | `SESSION_TIMEOUT_SECONDS` | no | seconds to wait for a session to become Ready |
  30. | `GDS_AGENT_MAX_RESULT_ROWS` / `_CHARS` / `_CELL_CHARS` | no | tool output limits (500 / 100000 / 200) |
  31. | `NEO4J_READ_ONLY` | no | `write_neo4j_cypher` stays hidden unless this is `false` |
  32. By default the server uses STDIO transport for local MCP clients. For HTTP-native clients, run the server with streamable HTTP:
  33. ```bash
  34. gds-agent --transport http --host 127.0.0.1 --port 8000 --path /mcp
  35. ```
  36. 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.
  37. ## GDS Aura Graph Analytics (sessions)
  38. 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`.
  39. Session mode requires Aura API credentials (see the configuration reference above) in the same `.env` file or `env` block as the database credentials.
  40. 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.
  41. # The skill
  42. `[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](skills/neo4j-graph-data-scientist/references/troubleshooting.md) reference guide, as well as general data science best practices.
  43. # Cypher tools
  44. `read_neo4j_cypher`, `write_neo4j_cypher`, and `get_neo4j_schema` are tools on this server. `get_neo4j_schema` calls APOC (`apoc.meta.schema`). `write_neo4j_cypher` is left off the tool list unless `NEO4J_READ_ONLY=false`.
  45. # Example dataset
  46. To load a London underground example dataset:
  47. 1. Fork and clone the repository
  48. 2. Install the Neo4j database with GDS plugin:
  49. Download the Neo4j Desktop from [Neo4j Download Center](https://neo4j.com/download/)
  50. Install the GDS plugin from the Neo4j Desktop
  51. Create a new database and start it
  52. 3. Populate .env file with necessary credentials:
  53. ```bash
  54. NEO4J_URI=bolt://localhost:7687 # or your database URI
  55. NEO4J_USERNAME=neo4j # or your db username
  56. NEO4J_PASSWORD=your_password
  57. ```
  58. 4. Load the London Underground dataset with the following command ([uv](https://docs.astral.sh/uv/getting-started/installation/) resolves the script's dependencies automatically):
  59. ```bash
  60. uv run import_data.py --undirected
  61. ```
  62. Connect to your DB and querying the graph from [Neo4j workspace](https://workspace-preview.neo4j.io/workspace/),
  63. you should see:
  64. London Underground Graph
  65. # Start the server for dev
  66. 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.
  67. 2. To try the plugin (MCP server + skill) from your working tree: `claude --plugin-dir .` from the repository root.
  68. # Releases
  69. 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.
  70. # How to contribute
  71. 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`.
  72. The CI build in github action requires all codestyle checks and tests to pass.
  73. To run and fix codestyle checks locally, in the `/mcp_server` directory, run:
  74. ```bash
  75. uv sync --dev
  76. ```
  77. to setup the python environment. And then,
  78. ```bash
  79. uv run pytest tests -v -s
  80. uv run ruff check
  81. uv run ruff format
  82. ```
  83. for all tests and codestyle fixes.
  84. # Feature request and bug reports
  85. To report a bug or a new feature request, raise an issue.
  86. If it is a bug, include the full stacktrace and errors.
  87. 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.
  88. # Additional resources
  89. Details about the architecture, benchmark results and analysis: [https://arxiv.org/abs/2508.20637](https://arxiv.org/abs/2508.20637).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.