Dgraph MCP Server 实战指南:用 Claude 等 AI 助手通过 MCP 协议查询和管理 Dgraph 图数据库

发布时间:2026/11/20 3:28:23

Dgraph MCP Server 实战指南:用 Claude 等 AI 助手通过 MCP 协议查询和管理 Dgraph 图数据库 数据库图数据库分布式数据库后端【免费下载链接】dgraphhigh-performance graph database for real-time use cases项目地址https://gitcode.com/gh_mirrors/dg/dgraph点击查看免费下载Dgraph MCPMaster Control Protocol服务器是 Dgraph 官方内置的一项能力它把 Dgraph 的 Schema 管理、DQL 查询与变更能力封装为标准 MCP 工具让 Claude Desktop、Cursor 等支持 MCP 协议的 AI 客户端可以直接用自然语言对话操作图数据库。本文基于 dgraph/cmd/mcp 模块的官方文档结合 mcp_server.go、run.go 与 alpha 的 HTTP 接入代码完整讲解两种接入方式、全部工具与资源清单、配置步骤与排错思路。读完本文你将能独立把本地或远程 Dgraph 实例接入任意 MCP 客户端并理解其读写权限控制与底层实现原理。Dgraph MCP 是什么Dgraph MCP 是一个基于 Dgraph 的 Master Control ProtocolMCP实现为 AI 智能体提供高级图数据库管理与查询能力。它不是一个独立的数据库服务而是一层翻译层把 MCP 客户端如 Claude发来的工具调用请求翻译成对 Dgraph Alpha 的 DQL 操作。从代码结构看整个模块由三部分构成run.go定义dgraph mcp子命令负责解析参数并启动 STDIO 模式的 MCP 服务器mcp_server.go核心实现注册全部 MCP 工具、资源和 Promptmcp_server_sse_test.goSSE 模式的端到端集成测试验证工具、资源、Prompt 的可用性。两种访问方式官方文档明确指出你可以通过两种方式访问 MCP 服务器通过 dgraph alpha 的 HTTP 端点启动 alpha 时开启 MCP 功能Alpha 会在 HTTP 端口暴露/mcp/sse与/mcp-ro/sse两个 SSEServer-Sent Events端点通过 Go 代码 / 命令行直接运行dgraph mcp子命令以 STDIO 模式与客户端通信。这两种方式底层复用同一个NewMCPServer构造函数定义于 mcp_server.go区别仅在于传输层alpha 走 HTTP SSE独立子命令走标准输入输出流。方式一通过 Dgraph Alpha 的 HTTP 端点接入开启 Alpha 的 MCP 功能Alpha 默认不开启 MCP 端点需要显式传入--mcp标志。在 alpha/run.go 中该标志定义如下flag.Bool(mcp, false, run MCP server along with alpha.)启动命令示例dgraph alpha --mcp当该标志为真时setupServer 会同时注册两个端点/mcp读写模式readOnlyfalse/mcp-ro只读模式readOnlytrue两个端点都通过setupMcp注册到 alpha 的 HTTP 路由上if enableMcp { if err : setupMcp(baseMux, buildConnectionString(laddr, grpcPort()), /mcp, false); err ! nil { log.Fatal(err) } if err : setupMcp(baseMux, buildConnectionString(laddr, grpcPort()), /mcp-ro, true); err ! nil { log.Fatal(err) } }setupMcpalpha/run.go#L433-L456内部做了三件事调用mcp.NewMCPServer构造服务器、用server.NewSSEServer包装成 SSE 服务、再包一层 CORS 处理函数后挂载到路由。这意味着浏览器类 MCP 客户端如 Claude Desktop可以直接跨域访问该端点。MCP 客户端配置在支持 MCP 的客户端Claude Desktop、Cursor 等配置文件中添加以下 JSON 即可只读配置{ dgraph-mcp-ro: { serverUrl: http://localhost:8080/mcp-ro/sse } }读写配置{ dgraph-mcp: { serverUrl: http://localhost:8080/mcp/sse } }其中8080是 alpha 默认的 HTTP 端口可通过--http_port调整路径必须带/sse后缀这是 MCP SSE 传输的端点约定。集成测试 mcp_server_sse_test.go 也验证了这一路径格式port, err : c.GetAlphaHttpPublicPort(0) serverURL : fmt.Sprintf(http://localhost:%s/mcp/sse, port) mcpClient, err : client.NewSSEMCPClient(serverURL)安全提示/mcp端点包含alter_schema与run_mutation两个破坏性工具若你的 alpha 暴露在公网务必通过--mcp配合 ACL 与 TLS 配置使用只读场景优先选择/mcp-ro端点。方式二通过 Go 代码 / 命令行以 STDIO 模式接入安装与运行这种方式要求本机已安装 dgraph 二进制文件。mcp子命令在 run.go 中定义归属于tool命令组Mcp.Cmd cobra.Command{ Use: mcp, Short: Run Dgraph MCP server, Long: A Dgraph MCP server is a long running process that provides an STDIO interface for running mcp server. , ... Annotations: map[string]string{group: tool}, }该子命令支持两个参数参数简写默认值说明--conn-str-c空Dgraph 连接字符串格式为dgraph://host:port--read-only无false以只读模式运行 MCP 服务器连接字符串的端口是gRPC 端口默认 9080而非 HTTP 端口。alpha 内部在构建自连接字符串时也遵循这一约定alpha/run.go#L458-L460func buildConnectionString(addr string, port int) string { return fmt.Sprintf(dgraph://%s:%d, addr, port) }MCP 客户端配置在 MCP 客户端配置文件中添加{ mcpServers: { dgraph: { command: dgraph_binary, args: [mcp, -c, dgraph://localhost:9080] } } }commanddgraph 二进制的实际路径Windows 上可写dgraph.exeargs中的mcp指定子命令-c指定连接字符串如需只读模式追加--read-only参数。客户端会以子进程方式启动该命令通过 STDIO 与 MCP 服务器通信。服务器在 run() 中通过server.ServeStdio(s)启动。连接重试机制值得一提的细节getConnmcp_server.go#L29-L52在首次打开连接失败时会自动重试最多 3 次间隔随次数递增0s、1s、2sconn, err : dgo.Open(connectionString) if err ! nil { for i : range 3 { time.Sleep(time.Second * time.Duration(i)) conn, err dgo.Open(connectionString) if err nil { break } } ... }连接对象以包级变量dgraphConnection缓存并用互斥锁保护后续工具调用复用同一连接避免重复建连开销。Claude Desktop 本地接入步骤官方文档给出了 macOS 上配置 Claude Desktop 的完整流程从 Claude 官网下载并安装 Claude.app在 macOS 上配置文件位于~/Library/Application Support/Claude创建claude_desktop_config.json内容填入上文任一 MCP 配置本地体验推荐 STDIO 模式无需serverUrl的 SSE 配置则使用command方式完全关闭 Claude 应用后重新打开点击工具tools图标检查 MCP 工具列表是否已加载现在你就可以直接用自然语言与 Claude 对话让它操作你的 Dgraph 实例了。注Linux/Windows 下 Claude Desktop 的配置目录不同请以官方客户端说明为准其他支持 MCP 的客户端如 Cursor、VS Code 扩展配置格式类似区别仅在于配置文件位置。MCP 工具与资源全解析NewMCPServermcp_server.go#L58-L445注册了 6 个工具、2 个资源与 1 个 Prompt。集成测试 mcp_server_sse_test.go 对工具清单做了断言与下述列表完全一致。工具清单工具名功能关键参数只读get_schema获取 Dgraph DQL Schema无是validate_query_syntax校验 DQL 查询语法query必填、variables可选 JSON是run_query执行 DQL 查询query必填、variables可选 JSON是alter_schema修改 DQL Schemaschema必填否run_mutation执行 DQL 变更插入/删除mutation必填 JSON否get_common_queries获取常用查询示例如最短路径无是只读与读写分离的实现readOnly参数控制着工具注册。当readOnlytrue时mcp_server.go#L149 的if !readOnly分支被跳过alter_schema与run_mutation根本不会被注册。这就是/mcp-ro端点只读的底层保障——不是运行时拦截而是注册阶段就不暴露。工具注解ToolAnnotation每个工具都声明了 MCP 规范建议的四项注解供客户端进行安全提示alter_schemaReadOnlyHintfalse、DestructiveHinttrue、IdempotentHintfalserun_mutationReadOnlyHintfalse、DestructiveHinttrue、IdempotentHintfalse查询类工具get_schema、run_query、validate_query_syntax、get_common_queries全部标记为只读、幂等、非破坏。各工具的工作原理get_schema通过只读事务执行 DQL 内建查询schema {}并返回 JSON 结果txn : conn.NewReadOnlyTxn() ... resp, err : txn.Query(ctx, schema {}) return mcp.NewToolResultText(string(resp.GetJson()))validate_query_syntax调用 Dgraph 官方解析器dql.Parse做语法与语义校验。它需要构造dql.Request结构体variables参数按map[string]string解析后一并传给解析器。集成测试覆盖了多种合法与非法场景mcp_server_sse_test.go#L223-L280不存在的函数名foo is not valid、未声明的变量Type of variable $notname not specified、变量误用Variables are not used properly都会被正确报错。run_query在只读事务中执行带变量的查询。variables参数是一个 JSON 字符串支持 string、number、boolean 三类值例如{$param1: value1, $param2: 123, $param3: true}实现上先把 JSON 反序列化为map[string]any再按类型转换为map[string]string传给QueryWithVars浮点数用strconv.FormatFloat保留完整精度、布尔用FormatBool、null转成字符串null。若变量值是嵌套对象等复杂结构会返回could not convert complex variable错误测试用例见 mcp_server_sse_test.go#L339-L348。alter_schema调用 dgo 客户端的conn.SetSchema(ctx, schema)执行 DDL成功返回Schema updated successfully。run_mutation接收 JSON 格式的变更载荷示例{set: [{ uid: _:1, n: Foo, m: 20, p: 3.14 }]}表示用空白标识符_:1创建一个节点属性 nFoo、m20、p3.14删除节点则用{ delete: [{ uid: 0xfa12 }]}实现中通过txn.Mutate(ctx, api.Mutation{SetJson: ..., CommitNow: true})执行并即时提交成功后返回创建 UID 的数量mcp_server.go#L235-L242。集成测试断言插入 1 个节点会返回Mutation completed, 1 UIDs created。资源ResourcesMCP 服务器还注册了 2 个文本资源客户端可以直接读取资源 URI名称内容dgraph://schemadgraph_schema当前 Dgraph DQL Schematext/plaindgraph://common_queriesdgraph_common_queries常用 DQL 查询示例含最短路径查询模板其中dgraph://common_queries提供的最短路径查询模板mcp_server.go#L361-L381很有实战价值{ q(func: eq(guid, first guid) { // 先取出第一个 uid a as uid } q1(func: eq(guid, second guid)) { // 再取出第二个 uid b as uid } path as shortest(from: uid(a), to: uid(b), numpaths: 5, maxheapsize: 10000) { connected_to facets(weight) // 有边权重时保留 facets(weight)权重相同时去掉 } path(func: uid(path)) { uid } }Promptquick_start_prompt服务器内置了一个quick_start_prompt其内容通过//go:embed prompt.txt直接编译进二进制mcp_server.go#L23-L24。该 Prompt 从 prompt.txt 读取为 LLM 定义了完整的交互行为规范包括连接校验先用get_schema验证连接可用性Schema 探索解析出全部谓词与类型以可读结构呈现查询执行先validate_query_syntax校验、再run_query执行、最后解释结果变更安全执行删除等破坏性操作前必须向用户确认并警告删除不可逆、需先备份向量搜索支持识别相似度/最近邻意图识别float32vector类型字段使用similar_to函数最佳实践内存缓存 Schema、维护查询历史、善用代码块与项目符号格式化输出。Prompt 中给出的向量搜索示例query vectorSearch($vec: [float]) { vecSearch(func: similar_to(embedding, $vec, 5)) { uid name embedding } }DQL 要点速查来自内置 PromptPrompt 内嵌了一套 DQL 速查可视为 AI 助手操作 Dgraph 的行为基线常用语句query { ... }查询节点与边query me($foo: string, $bar: int) { ... }带变量查询mutation { set { ... } }插入/更新mutation { delete { ... } }删除schema {}查看当前 Schema数据类型stringUTF-8、int32/64 位、float、bool、datetimeRFC3339、geo地理点/形状、uid节点间连接、float32vector向量相似度搜索语法要点谓词用尖括号name数据用三元组subject predicate object .uid()按唯一标识取节点过滤函数eq、allofterms、anyofterms、has、le、ge、regexp、match等变量用var(func: ...)定义可复用块指令filter、cascade、normalize控制输出。端到端验证集成测试做了什么TestMCPSSE 是理解整个系统行为的最佳入口。它构建一个包含 1 个 Alpha 1 个 Zero 的本地集群连上/mcp/sse端点后依次验证服务器元数据初始化结果中 ServerInfo.Name 必须为Dgraph MCP Server版本号非空工具清单6 个工具全部存在且数量一致资源清单dgraph://schema与dgraph://common_queries均可读取且内容非空Prompt 清单quick_start_prompt存在且消息非空功能链路先alter_schema建立索引n: string index(term) .、m: int index(int) .、p: float index(float) .再run_mutation写入节点然后validate_query_syntax、run_query验证查询返回的 UID 符合0x...十六进制格式最后get_common_queries返回示例。这条链路完整覆盖了建 Schema → 写数据 → 校验查询 → 读数据的典型工作流也是你在自己环境中手工验证 MCP 服务器是否正常的最快路径。常见问题排查官方文档给出了三条基础排查方向结合源码可以进一步细化检查 Dgraph 连接设置STDIO 模式下确认-c指向的是gRPC 端口默认dgraph://localhost:9080不是 HTTP 端口SSE 模式下确认 alpha 已带--mcp标志启动且 HTTP 端口与路径/mcp/sse或/mcp-ro/sse拼写正确若配置了 TLS 或 ACL确认客户端连接字符串包含相应认证信息。验证 Go 模块依赖go.mod中依赖github.com/mark3labs/mcp-goMCP 协议实现与github.com/dgraph-io/dgo/v250Dgraph 客户端依赖缺失或版本不匹配会导致二进制无法编译或运行。构建可参考仓库根目录 Makefile 中的相关目标。仔细查看错误日志dgraph 使用 glog 输出日志。连接失败时 run.go 会打印Failed to initialize MCPServer: ...工具调用失败时各工具通过NewToolResultErrorFromErr返回具体原因例如Error opening connection with Dgraph Alpha、Error parsing query、Schema alteration failed、Error running mutation等客户端界面上会直接显示这些错误文本据此定位是网络问题、语法问题还是权限问题。一个值得注意的边界情况validate_query_syntax只做解析校验不校验谓词是否存在于 Schema 中谓词存在性由get_schema交叉核对所以 AI 助手的工作流是先get_schema摸清结构再校验语法、再执行查询。小结Dgraph MCP 为 AI 原生的图数据库操作提供了一条标准、安全的通道两种接入方式alpha 内置 SSE 端点/mcp读写、/mcp-ro只读适合 Claude Desktop 等 GUI 客户端dgraph mcp子命令的 STDIO 模式适合本地进程内嵌场景能力边界清晰只读模式在注册阶段就剔除alter_schema与run_mutation配合工具注解让客户端能做出安全提示开箱即用6 个工具 2 个资源 1 个内嵌 Prompt覆盖Schema 管理 → 语法校验 → 查询 → 变更 → 常用查询参考的完整闭环并内置向量相似度搜索支持。对照 mcp_server_sse_test.go 的测试链路你可以在自己的环境里完整复现这套工作流快速验证接入是否成功。赞分享数据库图数据库分布式数据库后端【免费下载链接】dgraphhigh-performance graph database for real-time use cases项目地址https://gitcode.com/gh_mirrors/dg/dgraph点击查看免费下载相关推荐RocketRide MCP Server 集成实战通过 MCP 协议让 AI 助手驱动 RocketRide 数据管线RocketRide MCP Server 集成实战通过 MCP 协议让 AI 助手驱动 RocketRide 数据管线 本篇技术指南围绕 packages/人工智能大模型数据工程后端RAG本地部署MCP 服务前端CANN驱动设备系统时间查询dcmi\_get\_device\_system\_timea nameEN US_TOPIC_0000002515503760 /a PrototMCP 服务数据库后端AI 应用MCP Toolbox for Databases 接入 Dgraph 图数据库Source 配置与 dgraph-dql 工具实战指南MCP Toolbox for Databases 接入 Dgraph 图数据库Source 配置与 dgraph dql 工具实战指南 MCP ToolboMCP 服务数据库后端AI 应用上一篇如何用WarcraftHelper终极优化魔兽争霸III免费插件完整配置指南下一篇终极指南如何免费解锁WeMod高级功能完整游戏修改体验创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
延伸阅读

更多相关文章

2026/11/20 6:47:40

格式排版改到崩溃?导师力荐这几个AI论文写作工具

想写论文又快又好,关键是用对 AI 工具、走对流程——资深教授普遍推荐:千笔AI(中文全流程首选) 豆包学术版(轻量高效) DeepSeek 学术版(理工 / 长文本) Grammarly Academic&#xff…

2026/11/20 7:17:29

上海 电工证 培训考试真题与备考技巧

上海电工证培训多久拿证?实操考试心里没底怕挂科怎么办? 你是不是也这样,看到【上海电工证培训】几个字就紧张,担心实操考试过不了,更怕耽误拿证时间?尤其像我们信阳浉河区的应届工程类毕业生,对【多久拿证】这个问题格外敏感,毕竟它关系到就业、上岗…

2026/11/20 7:17:29

电工证算是初级技工吗值不值得考

电工证算是初级技工吗值不值得考 证书过期了不知道怎么复审延期?别慌,这波操作我来教你,还有【电工证算是初级技工吗】的疑问,值不值得考也给你讲清楚。 电工证算是初级技工吗…

2026/11/20 7:17:29

电工证初次领证的年龄怎么算?电子证书怎么查?

电工证初次领证的年龄怎么算?电子证书怎么查? 你不知道去哪报名怕被中介坑,又担心电工证初次领证的年龄限制,其实这些问题都不是事儿,关键是要找对方法和渠道。现在电工证已经全面实行电子证书, 电子证书…

2026/11/20 7:17:29

电工证电子证书图片值不值得考?外省证书怎么转过来

电工证电子证书图片值不值得考?外省证书怎么转过来 之前考的证在外省能不能转过来?这个问题我问过太多次,现在终于搞明白了。如果你手里拿着的是 电工证电子证书图片 ,不管是高压还是低压,只要符合国家应急管理部门的规定,…

2026/11/20 7:17:29

你考室内布线什么电工证?真实经历告诉你实操考试心里没底怕挂科

你考室内布线什么电工证?真实经历告诉你实操考试心里没底怕挂科 实操考试心里没底怕挂科,这几乎是每个打算考室内布线电工证的学员心里的真实写照。我认识的一个新乡应届工程类毕业生小张,去年刚拿到低压电工证,第一次参加实操考试时手都在抖,结果因为一…

2026/11/20 7:12:29

井冈山电工证复审考试怎么报?考前押题全攻略来了

井冈山电工证复审考试怎么报?考前押题全攻略来了 不知道去哪报名怕被中介坑?现在考电工证越来越火,但很多人还是被各种信息绕得晕头转向,尤其是井冈山地区的电工证复审考试,怎么报名、怎么准备、怎么通过,真的成了一个大问题。如果你正在为井冈山电工证…

2026/11/19 22:14:34

电工证考试口诉怎么准备值不值得考

电工证考试口诉怎么准备值不值得考 实操考试心里没底怕挂科,这是大多数准备考电工证的人心里最真实的感受。尤其是面对【电工证考试口诉】环节,很多人不知道该怎么准备,甚至担心自己说不好就被淘汰。其实,只要掌握方法, 值不值得考…

2026/11/20 6:48:54

桑植县考电工证千万别踩坑!报名全流程教你避坑

桑植县考电工证千万别踩坑!报名全流程教你避坑 你是不是也遇到过这种情况:想考个电工证,但不知道从哪儿下手,怕被中介坑,怕花冤枉钱,更怕考了证还不能用?别急,这正是你该看这篇文章的原因。在桑植县考电工证,确实有很多人被坑过,但只要你知道流程、…

2026/11/20 0:00:30

电力电缆制作特种证过期了怎么复审?郑州报考避坑指南全解析

电力电缆制作特种证过期了怎么复审?郑州报考避坑指南全解析 证书过期了不知道怎么复审延期?作为一名在郑州从事电力电缆制作特种作业多年的项目管理员,我亲身经历过证书过期后被责令停工的尴尬场面。那天,我在平顶山某工地进行电缆敷设作业时,被当地应急…

2026/11/20 0:00:30

葫芦岛考低压电工证过期怎么复审?考前押题帮你稳过

葫芦岛考低压电工证过期怎么复审?考前押题帮你稳过 证书过期了不知道怎么复审延期,耽误工作还影响收入?别急,今天就给你讲讲葫芦岛考低压电工证的有效期、复审流程,还有考前押题怎么用,保证你少走弯路。 低压电工证有效期与复审规则…

2026/11/20 0:00:30

济阳从哪里学电工证良心建议:怕考不过白交培训费?看完这篇全明白

济阳从哪里学电工证良心建议:怕考不过白交培训费?看完这篇全明白 你是不是也担心,花了钱去学电工证,结果考试还是不过,白白浪费时间和金钱?特别是济阳这边,培训机构多得是,但真正靠谱的又有几个?今天我就来给你掏心窝子,讲讲济阳从哪里学电工证的良…

2026/11/20 6:49:17

面向复杂光照与角度的宠物面部识别鲁棒性增强策略

在智慧养宠时代,基于视觉的宠物身份识别技术正逐步从实验室走向家庭应用。然而,与配合度高的人类不同,宠物是典型的“非合作生物识别对象”——它们不会主动配合摄像头调整姿态,更无法控制光照环境。实际应用中,我们常…

2026/11/19 17:18:32

SSM电子书店源码全解析:结构、原理、部署与排错实战

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

还想了解更多?直接咨询顾问

免费诊断 + 免费方案 + 透明报价。

全国咨询热线400-8866-253
免费获取方案
☎咨询二维码 ☎ ↑