Neo4j GDS Agent

GDS Agent

GDS Agent 让大模型能够在 Neo4j 图数据上进行推理和数据科学工作，它使用两种组件：

• 工具 — 一个 MCP 服务，提供 Neo4j Graph Data Science (GDS) 算法：中心性、社区检测、路径查找、相似度、节点嵌入和机器学习流水线。
• 技能 — 一个 Agent 技能（neo4j-graph-data-scientist），教会 Agent 如何以及何时使用这些工具，并介绍图数据科学的最佳实践。

它适用于任何支持 MCP 的运行环境——Claude Code、Claude Desktop、claude.ai、OpenAI Codex、Cursor、VS Code/Copilot、Gemini CLI——也能通过编程方式与 Agent 框架配合使用。在自托管的 Neo4j 上，它使用 GDS 插件；在 AuraDB 上，它使用 GDS Aura Graph Analytics 会话，并通过 STDIO 或 HTTP 传输。

设置完成后，你可以就 Neo4j 图数据提出任何问题并获得解答。你可以与 Agent 协作，以图数据科学家的身份解决复杂任务。

安装

运行环境	工具 (MCP)	技能	指南
Claude Code	/plugin marketplace add neo4j-contrib/gds-agent → /plugin install gds-agent@neo4j-gds	与插件捆绑	设置
Claude Desktop	从 releases 下载 .mcpb，然后双击打开	在“设置” → “技能”中上传技能 zip 文件	设置
OpenAI Codex	codex mcp add neo4j-gds -- uvx gds-agent	npx skills add neo4j-contrib/gds-agent -a codex	设置
Cursor	一键徽章	npx skills add neo4j-contrib/gds-agent -a cursor	设置
VS Code / Copilot	一键徽章或 .vscode/mcp.json	npx skills add neo4j-contrib/gds-agent -a copilot	设置
Gemini CLI	gemini extensions install https://github.com/neo4j-contrib/gds-agent	与扩展捆绑	设置
你自己的 Agent	任意 MCP 客户端（stdio/HTTP）	将 SKILL.md 注入指令中	设置

大多数本地设置都需要先安装 uv（服务通过 PyPI 中的 uvx gds-agent 运行）。通用 MCP 客户端会通过 stdio 运行 uvx gds-agent，并使用下方的环境变量。

配置参考

设置为环境变量（或使用你的 harness 安装程序中的凭据表单）：

变量	必需	用途
NEO4J_URI	是	neo4j:// 或 neo4j+s:// 连接 URI
NEO4J_USERNAME / NEO4J_PASSWORD	是	数据库凭据
NEO4J_DATABASE	否	数据库名称（默认为 neo4j）
AURA_API_CLIENT_ID / AURA_API_CLIENT_SECRET	会话模式	用于 Aura Graph Analytics 的 Aura API 凭据
AURA_API_PROJECT_ID	否	仅当 API 客户端可访问多个项目时需要
SESSION_MEMORY_GB / SESSION_TTL_HOURS	否	会话默认值（8 GB / 12 h）
SESSION_TIMEOUT_SECONDS	否	等待会话变为 Ready 的秒数
GDS_AGENT_MAX_RESULT_ROWS / _CHARS / _CELL_CHARS	否	工具输出限制（500 / 100000 / 200）

默认情况下，服务使用 STDIO 传输方式供本地 MCP 客户端使用。对于原生支持 HTTP 的客户端，请使用可流式传输的 HTTP 启动服务：

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

等效的环境变量为 GDS_AGENT_TRANSPORT、GDS_AGENT_HOST、GDS_AGENT_PORT 和 GDS_AGENT_PATH。也支持 Neo4j MCP 风格的 NEO4J_TRANSPORT 和 NEO4J_MCP_SERVER_* 名称。

GDS Aura Graph Analytics（会话）

服务会检测已连接的 Neo4j 是否安装了 GDS 插件，或者是否应使用 GDS Aura Graph Analytics 会话。检测会在启动时运行 gds.session.list()；如果成功，则使用会话模式，并通过 gds.graph.project.remote 创建图投影。

会话模式需要 Aura API 凭据（参见上方配置参考），并且这些凭据必须与数据库凭据位于同一个 .env 文件或 env 块中。 会话由 Agent 显式管理：会话模式下会提供三个额外工具（list_sessions、create_session 和 delete_session）。必须先使用 create_session 创建会话，随后 project_graph_cypher 会将每个图投影到其必需参数 sessionName 指定的会话中，而算法调用会根据 graphName 自动路由到正确的会话。大多数工作流只需一个容纳所有图的会话；多个会话则允许并行运行分析。若要调整会话大小（例如发生 OOM 后），请删除会话并使用更大的 memoryGB 重新创建。服务创建的所有会话名称都带有 mcp_ 前缀。Aura 会话的费用与数据库分开计收。

技能

Claude Code 插件、Gemini 扩展、npx skills 和发布版技能 zip 均从同一位置读取 [skills/neo4j-graph-data-scientist](skills/neo4j-graph-data-scientist/SKILL.md)。它涵盖 GDS 专属工作流最佳实践，并提供故障排除参考指南，以及通用数据科学最佳实践。它面向 gds-agent 和 mcp-neo4j-cypher MCP 服务。

与 GDS 配合使用只读 Cypher

GDS 服务有意不执行任意 Cypher——它唯一的 Cypher 入口是图投影。若要让 Agent 也能读取底层数据（检查属性、聚合数据、验证算法结果），请将其与只读模式下的 [mcp-neo4j-cypher](https://github.com/neo4j-contrib/mcp-neo4j) 服务配合使用。

Claude Code 插件和Gemini CLI 扩展已内置该服务：一次安装即可使用相同凭据配置两个服务，并且 NEO4J_READ_ONLY=true 会移除其写入工具。NEO4J_RESPONSE_TOKEN_LIMIT 会限制读取查询响应的大小（以 token 计），避免大型结果让模型不堪重负；省略此项则不限制 Cypher 侧的响应。对于其他运行环境，请在 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"
  }
}

示例数据集

要加载 London Underground 示例数据集：

1. Fork 并克隆此仓库
2. 安装带有 GDS 插件的 Neo4j 数据库： 从 Neo4j 下载中心下载 Neo4j Desktop 从 Neo4j Desktop 安装 GDS 插件 创建新数据库并启动
3. 在 .env 文件中填入所需凭据：

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

4. 使用以下命令加载 London Underground 数据集（uv 会自动解析脚本的依赖项）：

 uv run import_data.py --undirected

连接到数据库并通过 Neo4j 工作区查询图后， 你应该会看到： London Underground 图

启动开发服务器

1. 在 /mcp_server 目录中运行 uv sync --dev，然后运行 uv run gds-agent，即可单独启动 MCP 服务；也可以运行 claude，通过 Agent 启动 claude-cli。
2. 若要从工作树试用插件（MCP 服务 + 技能）：在仓库根目录运行 claude --plugin-dir .。

发布

版本号由 scripts/bump_version.py 在 pyproject.toml 和所有分发清单中保持同步。推送 v* 标签会触发发布工作流。

如何贡献

从你 Fork 的仓库分支向本仓库的 main 分支发起拉取请求，例如 mygithubid:add-new-algo -> neo4j-contrib:main。

GitHub Actions 中的 CI 构建要求所有代码风格检查和测试均通过。

若要在本地运行并修复代码风格检查，请在 /mcp_server 目录中运行：

uv sync --dev

以设置 Python 环境。然后运行：

uv run pytest tests -v -s
uv run ruff check
uv run ruff format

以运行所有测试并修复代码风格问题。

功能请求和错误报告

若要报告错误或请求新功能，请提交 issue。 如果是错误，请附上完整的堆栈跟踪和错误信息。 如有相关日志，请附上 mcp_server_neo4j_gds.log。如果 gds Agent 从源代码运行，该文件位于 /mcp_server/src_mcp_server_neo4j_gds 目录中；如果通过 Claude 运行，则位于日志路径下（例如，Mac 上 Claude Desktop 的 /Library/Logs/Claude）。请尽可能附上可用于复现问题的相关最小数据集。

更多资源

GDS Agent 可与其他 MCP 服务配合使用，例如提供额外 Neo4j 工具的服务：https://github.com/neo4j-contrib/mcp-neo4j Arxiv 论文，包含架构和基准测试结果的详细信息：https://arxiv.org/abs/2508.20637。