{ "markdown": "# graph-query-mcp\n\n\n\n\n

\n \"License\"\n \"GitHub\n \"Last\n \"Open\n \"PyPI\n \"PyPI\n \"Built\n

\n\n\n\nSurgical queries against an Obsidian / vault knowledge graph. Loads a `graph.json` (NetworkX node-link format) once at startup and answers targeted questions without making Claude read a 50K-line graph report.\n\nDesigned to pair with [`graphify`](https://github.com/mycelium-hq/ai-brain-starter) (the graph-building skill in ai-brain-starter), but the server accepts any graph in NetworkX node-link JSON. Supports up to two scopes (primary + secondary, e.g. personal + team).\n\n## Why use this\n\nIf you've already run `graphify` on a vault, you've got a `graph.json` and a `GRAPH_REPORT.md`. Reading the full report into Claude burns thousands of tokens for every question. This MCP loads the graph once at startup, answers in <50ms, and never spills the whole graph into context.\n\n## Tools\n\n| Tool | What it does |\n|---|---|\n| `search_nodes(query, scope, limit)` | Fuzzy match against node names. Returns node IDs ranked by exact / starts-with / contains. |\n| `get_neighbors(node_id, scope, max_hops, limit)` | Connected nodes within N hops, sorted by degree. |\n| `find_path(source, target, scope)` | Shortest path between two concepts. Auto-fuzzy-matches both ends. |\n| `get_top_nodes(scope, n)` | Highest-degree nodes (the \"god nodes\"). |\n| `query_subgraph(concepts, scope, max_hops, limit)` | Subgraph around a list of concepts; reports node + edge counts. |\n| `get_node_info(node_id, scope)` | Full metadata + top neighbors for one node. |\n| `get_community_members(node_id, scope, limit)` | All nodes in the same community-detection cluster. |\n\nScope defaults to `personal`; pass `scope=\"onde\"` (or whatever secondary scope name you've configured) for the second graph.\n\n## Configuration\n\nTwo env vars, both optional:\n\n| Env var | Default | Use for |\n|---|---|---|\n| `GRAPH_JSON_PATH` | `~/Documents/Vault/Meta/graphify-out/graph.json` | Primary graph (the `personal` scope) |\n| `SECONDARY_GRAPH_JSON_PATH` | `~/Documents/Vault/Team/Meta/graphify-out/graph.json` | Secondary graph (the `onde` scope, historical name) |\n\n`ONDE_GRAPH_JSON_PATH` is also accepted as a backward-compat alias for `SECONDARY_GRAPH_JSON_PATH`.\n\nIf a path doesn't exist at startup, the server logs a warning and the tools return a friendly error when that scope is queried. The server still starts — a missing secondary graph never blocks the primary.\n\n## Install\n\nOpen Claude Code, paste:\n\n /plugin marketplace add adelaidasofia/graph-query-mcp\n /plugin install graph-query-mcp@graph-query-mcp\n\n
Legacy install\n\n```bash\ngit clone https://github.com/adelaidasofia/graph-query-mcp.git ~/.claude/graph-query-mcp\ncd ~/.claude/graph-query-mcp\npip3 install --break-system-packages -r requirements.txt\n```\n\nRegister in your project `.mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"graph-query\": {\n \"type\": \"stdio\",\n \"command\": \"fastmcp\",\n \"args\": [\"run\", \"/Users/YOU/.claude/graph-query-mcp/server.py\"],\n \"env\": {\n \"GRAPH_JSON_PATH\": \"/path/to/your/vault/Meta/graphify-out/graph.json\"\n }\n }\n }\n}\n```\n\nRestart Claude Code, then `claude mcp list` should show `graph-query` connected.\n\n
\n\n## Generating the graph\n\nThis MCP doesn't build the graph; it queries one. Use [`graphify`](https://github.com/mycelium-hq/ai-brain-starter) (a skill in ai-brain-starter) to produce a `graph.json` from your vault, or any other NetworkX-compatible builder. The expected format is the output of `networkx.node_link_data(G)`.\n\n## Verification\n\n```bash\npython3 tests/integration/test_smoke.py\n# expected: PASSED — graph-query-mcp smoke (4 steps green)\n```\n\n## Architecture\n\nFastMCP, stdio transport, Python 3.10+. Graphs are loaded once at startup and cached in memory. No daemons, no listeners, no external services. NetworkX in-memory for query primitives.\n\n## Related MCPs\n\nSame author, same architecture pattern (FastMCP, draft+confirm on writes where applicable, vault auto-export, MIT):\n\n- [slack-mcp](https://github.com/adelaidasofia/slack-mcp) — multi-workspace Slack\n- [imessage-mcp](https://github.com/adelaidasofia/imessage-mcp) — macOS iMessage\n- [whatsapp-mcp](https://github.com/adelaidasofia/whatsapp-mcp) — WhatsApp via whatsmeow\n- [apollo-mcp](https://github.com/adelaidasofia/apollo-mcp) — Apollo.io CRM + sequences\n- [google-workspace-mcp](https://github.com/adelaidasofia/google-workspace-mcp) — Gmail / Calendar / Drive / Docs / Sheets\n- [substack-mcp](https://github.com/adelaidasofia/substack-mcp) — Substack writing + analytics\n- [parse-mcp](https://github.com/adelaidasofia/parse-mcp) — markitdown / Docling / LlamaParse router\n- [luma-mcp](https://github.com/adelaidasofia/luma-mcp) — lu.ma events\n- [graph-autotagger-mcp](https://github.com/adelaidasofia/graph-autotagger-mcp) — wikilink suggestions from the same graph format\n\n\n## Telemetry\n\nThis plugin sends a single anonymous install signal to `myceliumai.co` the first time it loads in a Claude Code session on a given machine.\n\n**What is sent:**\n- Plugin name (e.g. `slack-mcp`)\n- Plugin version (e.g. `0.1.0`)\n\n**What is NOT sent:**\n- No user identifiers, names, emails, tokens, or API keys\n- No file paths, message content, or anything from your work\n- No IP address is stored after dedup processing\n\n**Why:** Helps the maintainer know which plugins people actually install, so attention goes to the ones that get used.\n\n**Opt out:** Set the environment variable `MYCELIUM_NO_PING=1` before launching Claude Code. The hook will skip the network call entirely. Already-pinged installs leave a sentinel at `~/.mycelium/onboarded-` — delete it if you want to reset state.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n", "bytes": 6960, "sha": "8409463d407027a5b8775ee6d64680316538e4be5015d38436ca6bd4c55d4799", "repo_slug": "adelaidasofia/graph-query-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/plg_adelaidasofia_graph_query_mcp_graph_quer_af3969ed/readme" }