FastMCP server for surgical queries against a vault knowledge graph (NetworkX no

graph-query-mcp

针对 Obsidian / vault 知识图谱进行精确查询。启动时加载一次 graph.json（NetworkX 节点链接格式），并回答针对性问题，无需让 Claude 读取 5 万行的图谱报告。

此工具旨在与 graphify（ai-brain-starter 中用于构建图谱的技能）搭配使用，但服务也接受任何采用 NetworkX 节点链接 JSON 格式的图谱。最多支持两个范围（主要范围 + 次要范围，例如个人 + 团队）。

为什么要使用

如果你已在 vault 上运行过 graphify，就会有一个 graph.json 和一个 GRAPH_REPORT.md。每次提问时，将完整报告读入 Claude 都会消耗数千个 token。此 MCP 会在启动时加载一次图谱，在 50 毫秒内回答问题，并且绝不会将整个图谱泄露到上下文中。

工具

范围默认为 personal；对于第二张图，请传入 scope="onde"（或你配置的其他次要范围名称）。

配置

两个环境变量，均为可选：

也接受 ONDE_GRAPH_JSON_PATH，作为 SECONDARY_GRAPH_JSON_PATH 的向后兼容别名。

如果启动时路径不存在，服务会记录警告；查询该范围时，工具会返回易于理解的错误。服务仍会启动——次要图谱缺失绝不会影响主要图谱。

安装

打开 Claude Code 并粘贴：

/plugin marketplace add adelaidasofia/graph-query-mcp
/plugin install graph-query-mcp@graph-query-mcp

git clone https://github.com/adelaidasofia/graph-query-mcp.git ~/.claude/graph-query-mcp
cd ~/.claude/graph-query-mcp
pip3 install --break-system-packages -r requirements.txt

{
  "mcpServers": {
    "graph-query": {
      "type": "stdio",
      "command": "fastmcp",
      "args": ["run", "/Users/YOU/.claude/graph-query-mcp/server.py"],
      "env": {
        "GRAPH_JSON_PATH": "/path/to/your/vault/Meta/graphify-out/graph.json"
      }
    }
  }
}

此 MCP 不会构建图谱，而是查询图谱。使用 graphify（ai-brain-starter 中的一项技能）从你的知识库生成 graph.json，也可以使用任何其他兼容 NetworkX 的构建器。预期格式为 networkx.node_link_data(G) 的输出。

验证

python3 tests/integration/test_smoke.py
# expected: PASSED — graph-query-mcp smoke (4 steps green)

架构

FastMCP、stdio 传输、Python 3.10+。图谱在启动时加载一次，并缓存在内存中。没有守护进程、监听器或外部服务。使用内存中的 NetworkX 实现查询原语。

相关 MCP

同一作者、相同架构模式（FastMCP、适用时写入采用草稿 + 确认、知识库自动导出、MIT）：

• slack-mcp — 多工作区 Slack
• imessage-mcp — macOS iMessage
• whatsapp-mcp — 通过 whatsmeow 使用 WhatsApp
• apollo-mcp — Apollo.io CRM + 序列
• google-workspace-mcp — Gmail / Calendar / Drive / Docs / Sheets
• substack-mcp — Substack 写作 + 分析
• parse-mcp — markitdown / Docling / LlamaParse 路由器
• luma-mcp — lu.ma 活动
• graph-autotagger-mcp — 基于相同图谱格式提供 wikilink 建议

遥测

此插件会在某台设备上的 Claude Code 会话中首次加载时，向 myceliumai.co 发送一条匿名安装信号。

发送内容：

• 插件名称（例如 slack-mcp）
• 插件版本（例如 0.1.0）

不会发送的内容：

• 不发送用户标识符、姓名、电子邮件、令牌或 API 密钥
• 不发送文件路径、消息内容或任何工作相关内容
• 去重处理后不会存储 IP 地址

**原因：**帮助维护者了解用户实际安装了哪些插件，以便将精力投入到有人使用的插件上。

**选择退出：**在启动 Claude Code 前设置环境变量 MYCELIUM_NO_PING=1。此钩子将完全跳过网络调用。已发送过信号的安装会在 ~/.mycelium/onboarded-<plugin> 留下一个标记文件 — 如果想重置状态，请将其删除。

许可证

MIT。请参阅 LICENSE。