graphify-mcp
This MCP server builds and navigates a codebase knowledge graph so an AI assistant can orient, search, traverse, inspect, and keep graph data fresh without reading whole files.
Build or update a graph from a folder, including deep extraction, changed-file updates, clustering-only runs, and optional visualization skipping.
Run natural-language queries against the graph and find exact paths between two nodes.
Explain a node and show its metadata, type, source location, docstring, and community.
Add external sources such as arXiv papers or tweets via http/https URL.
Get a codebase overview, highest-degree “god nodes,” surprise cross-domain edges, and Leiden community summaries.
Check how semantic community naming can run and label communities via host LLM sampling, API-key backend, or placeholders.
Search nodes by text, list direct neighbors, and extract token-budgeted subgraphs around a node.
Check whether the graph is stale relative to git HEAD and whether to rebuild or update.
Allows adding a source from arXiv by URL, enabling the knowledge graph to include research papers as nodes.
Optionally used as a local backend for labeling communities with semantic names via the graphify_label_communities tool.
Optionally used as a backend API for labeling communities with semantic names via the graphify_label_communities tool.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@graphify-mcp give me an overview of the codebase graph"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
graphlore: an MCP server for codebase knowledge graphs
graphlore is a Model Context Protocol (MCP) server that lets AI coding
assistants navigate a codebase through its knowledge graph, instead of grepping
and reading file after file. It reads a graph built by
Graphify, joins every node to its real start..end
source span (Python via ast, other languages via tree-sitter), and answers
the questions text search cannot: who calls this, what breaks if it changes,
where a behavior lives.
Find code by what it does.
graphlore_locate("where are failed requests retried?")returns the enclosing symbol, its neighborhood and similar-but-unconnected code in one call: about 235 tokens, against about 61,800 for grep + read on httpx (benchmark).See the blast radius of a change.
graphlore_impact("Response")lists what depends on a symbol, production code before tests, each row withfile:line.Read only the code you need.
graphlore_fetchreturns a symbol's exact span under a token budget.Know how far to trust an answer. Results say how a name was matched, what a budget cut left out, and which files changed since the graph was built.
Local by default. The analysis tools read local files and need no API key;
GRAPHLORE_OFFLINE=1refuses every network path graphlore knows.
It works with any MCP client. Setup for Claude Code and Claude Desktop is below.
Quick start
Claude Code plugin (needs uv): installs the
server, the Graphify CLI and an exploration skill, with nothing to configure.
/plugin install graphlore --marketplace yasinyaman/graphloreOn Claude Code older than 2.1.275, run /plugin marketplace add yasinyaman/graphlore
and then /plugin install graphlore@graphlore.
Any other MCP client: install graphlore and the Graphify CLI that builds the graph, then register the server.
# graphlore is not on PyPI yet: install from GitHub
pip install "graphlore @ git+https://github.com/yasinyaman/graphlore"
pip install graphifyy && graphify install{
"mcpServers": {
"graphlore": {
"command": "graphlore",
"env": { "GRAPHLORE_PROJECT_DIR": "/absolute/path/to/your/project" }
}
}
}Claude Code: save this as
.mcp.jsonin the project root ("."works as the path).Claude Desktop: add it to
claude_desktop_config.json(macOS~/Library/Application Support/Claude/, Windows%APPDATA%\Claude\).
Optional extras, installed as graphlore[extra]: semble (semantic
graphlore_locate and the duplication scan), treesitter (spans for non-Python
languages; usually already present through Graphify), tiktoken (exact token
counts), watch (re-sync on file changes). Until the first PyPI release, use
the GitHub form wherever a message says pip install "graphlore[extra]":
pip install "graphlore[semble] @ git+https://github.com/yasinyaman/graphlore".
Then ask. The assistant builds the graph once and explores from there (output from the repository's small test fixture):
graphlore_build(".") # once; graphlore_build(".", update=True) after changes
graphlore_overview() # size, hubs, subsystems, suggested next steps
graphlore_impact("Response", hops=1)
2 node(s) depend on Response (≤1 hops, direction=dependents):
Client (distance 1) [returns] def: httpx/_client.py:50
DigestAuth (distance 1) [inferred] def: httpx/_auth.py:120A misspelled name gets a suggestion, not a guess:
No node matching 'Clinet'. Did you mean: Client (httpx/_client.py:50)?
Related MCP server: repo-graphrag-mcp
Tools
The server starts on the lean surface, 12 tools that cover the whole explore
loop (orient, find, traverse, blast radius, read the code). A small surface
helps a model pick the right tool.
Tool | What it answers |
| Call first: size, most connected nodes, communities, suggested next steps |
| A natural-language question → the enclosing symbol, its subgraph and hidden links (needs |
| Which nodes match this name or id |
| The direct neighbors of a node |
| The neighborhood around a node, under a token budget |
| Blast radius: what depends on a node, or what it depends on |
| A node's type, |
| A node's source code: the exact span, under a token budget |
| The subsystems (Leiden communities) of the codebase |
| Is the graph stale against git: fresh, update or rebuild |
| Build or update the graph with the Graphify CLI |
| Show or switch the project directory the server reads |
GRAPHLORE_TOOLSET=full exposes all 33: structure review (import and call
cycles, layer rules, dead-code candidates, same-named symbols, duplication),
framework routes and package API usage, tests for a symbol, signatures, git
diffs, community naming and the Graphify CLI passthroughs. The Claude Code
plugin runs on full.
→ Tool reference (all 33 tools, resources, prompts) · choosing a toolset
Benchmark
Tokens that reach the model to orient it in a code area, averaged over 6
queries on encode/httpx (2,101-node graph):
Approach | Tokens | Calls | Graph structure | Semantic search | Hidden links |
grep + read | 61,836 | ~14 | — | — | 0 |
semble alone | 1,613 | 1 | — | ✓ | 0 |
Graphify alone | 1,107 | 1 | ✓ | — | 0 |
semble + Graphify, separately | 2,721 | 4 | ✓ | ✓ | 0 |
| 235 | 1 | ✓ | ✓ | 7 |
That is 263× fewer tokens than grep + read and 11.6× fewer than running the two
tools separately. Those 235 tokens are a map (file:line plus neighborhood),
not the code; the code is fetched only where needed. Across Python, JS/TS, Go,
Java, Rust and C++ repositories, 70–96% of semantic hits land inside the
resolved symbol's real span.
Every repository measured is an HTTP-client library and the baseline is a naive grep, so treat the numbers as indicative. → Method, per-language results and caveats
FAQ
What is graphlore used for?
Giving an AI coding assistant a cheap, structural view of a repository: onboarding to unfamiliar code, tracing how a feature works end to end, finding what a change would break, and reviewing structure (cycles, layering, dead or duplicated code).
How is it different from Graphify's own MCP server?
They overlap more than they differ. Graphify's embedded server already has
graph navigation, token-budgeted subgraphs, an HTTP transport, multi-project
serving and PR triage tools graphlore lacks. graphlore adds the span engine and
what it makes possible: semantic locate joined to the enclosing symbol,
source hydration (fetch, skeleton), route and package-API extraction,
cosmetic-vs-structural freshness, and calls through a module object
(mod.func()) that the graph leaves out. Prefer one server per project.
→ How graphlore works
Does it replace grep?
No. An exact identifier is found faster with rg. graphlore earns its place on
multi-hop questions (who calls this, what breaks if it changes) and on
orientation in unfamiliar code. Every answer carries file:line, so it can be
checked with a plain read.
Is it an agent memory?
No. It has no remember or recall tools and keeps no notes between sessions. It is a read-mostly view of a code graph; the only thing it persists is community names.
Does it need an API key or send my code anywhere?
The analysis tools read local files and need no key. A few paths can reach the
network: the first semantic search downloads an embedding model, the first use
of a language downloads its tree-sitter grammar, Graphify can call an LLM
backend when you set its key, and graphlore_add fetches a URL.
GRAPHLORE_OFFLINE=1 refuses or restricts the ones graphlore controls; the
table linked below also lists what it cannot constrain.
→ What reaches the network, and when
Which languages are supported?
Python works out of the box through the standard library. JS/TS, Go, Java,
Kotlin, Scala, C#, Rust, Swift, C/C++, Ruby, PHP and the other languages
tree-sitter covers need the [treesitter] extra; without it, non-Python files
fall back to nearest-line matching. Package-API extraction reads all of
these; route extraction reads Python, JS/TS, Go, Java, Kotlin, C#, Rust, Ruby
and PHP frameworks
(tool reference),
and both say which files they did not read.
What was measured in each language,
on 31 real repositories.
Why do I see only 12 tools?
lean is the default surface. Set GRAPHLORE_TOOLSET=full for all 33.
How does the graph stay up to date?
graphlore_freshness says whether to update or rebuild, and
graphlore_build(".", update=True) re-extracts changed files. Answers also flag
their own files that changed since the build. A git post-commit hook or the
opt-in watcher automates it.
→ Keeping the graph fresh
Was this project called graphify-mcp?
Yes. It was renamed because graphifyy ships a graphify-mcp command of its
own. The old GRAPHIFY_* environment variables still work.
Known limits
One active project at a time;
graphlore_projectswitches it (stdio only).No extractor of its own: the
graphifyCLI builds the graph, andbuild/query/path/explain/addare thin wrappers over it.No PR or review-thread tooling.
Calls through an object, a callback or dynamic dispatch are not in the graph, so an empty answer means "no edge was indexed", not "nothing calls this".
Documentation
Tool reference: all 33 tools, resources, prompts, what a result carries
How graphlore works: resolved edges, import checks, analysis scope, freshness, semantic bridge, naming communities
Configuration: toolsets, HTTP transport and security, offline mode, environment variables
Benchmark: method, cross-language results, caveats
Development
pip install -e ".[dev,treesitter]"
ruff check .
mypy
pytest -qLicensed under MIT.
Available Tools
16 toolsgraphify_addA
Add an external source to the graph (arXiv paper, tweet, etc.). http/https only.
Args: url: Source URL to add. author: Original author tag (optional). contributor: Tag for who added it (optional).
Inputs: url (required), author, contributor. Returns: result
graphify_buildA
Build or update a knowledge graph from a folder. (Writes to graphify-out/.)
Args: path: Folder to extract the graph from (relative to the project dir or absolute). mode: "deep" -> more aggressive INFERRED edges; empty -> default. update: True -> re-extract only changed files and merge into the existing graph. cluster_only: True -> rerun clustering only, without re-extraction. no_viz: True -> skip the HTML visualization (faster for development).
Inputs: path, mode, update, cluster_only, +1 more. Returns: result
graphify_communitiesBRead-only
Summarize Leiden communities with sizes and sample members.
Inputs: as_json. Returns: result
graphify_explainCRead-only
Return everything Graphify knows about a node.
Inputs: node (required). Returns: result
graphify_freshnessARead-only
Check whether graph.json is stale relative to the current git HEAD.
Prefers the commit graphify recorded the graph was built from
(built_at_commit) over the file mtime — robust across checkouts where
mtime is reset — and flags both modified and newly-added (untracked) files.
Recommends graphify_build(update=True) if stale.
Inputs: as_json. Returns: result
graphify_god_nodesBRead-only
List the highest-degree (most connected) 'god nodes'.
Inputs: top_n, as_json. Returns: result
graphify_label_communitiesA
Give the Leiden communities human-readable names.
Args:
method: "auto" -> host-LLM sampling if the client supports it, else a
configured backend key (graphify CLI), else "Community N" placeholders.
"sampling" -> force host-LLM sampling (no API key needed).
"cli" -> force the graphify backend (GEMINI_API_KEY/OPENAI_API_KEY/...
or a local ollama). "placeholder" -> no LLM at all.
limit: Only the largest limit communities are named, to stay cheap.
sample_size: Member labels per community handed to the model.
Inputs: method, limit, sample_size, as_json. Returns: result
graphify_neighborsCRead-only
List the direct (1-hop) neighbors of a node, with relations.
Inputs: node (required), as_json. Returns: result
graphify_node_detailsCRead-only
Show a node's full metadata: type, source file/line, docstring, community.
Inputs: node (required), as_json. Returns: result
graphify_overviewARead-only
One-shot orientation: call this FIRST.
Returns graph size, top god nodes, community count, surprise-edge count and suggested starting questions — enough to plan further exploration cheaply.
Inputs: top_n, as_json. Returns: result
graphify_pathBRead-only
Find the exact path between two nodes (e.g. "DigestAuth" -> "Response").
Inputs: node_a (required), node_b (required). Returns: result
graphify_queryARead-only
Run a natural-language query against the graph.
Args: question: Natural-language question, e.g. "what connects attention to the optimizer?" dfs: True -> trace a specific path in depth. budget: If >0, cap the number of tokens returned (e.g. 1500).
Inputs: question (required), dfs, budget. Returns: result
graphify_sampling_statusARead-only
Capability test: how can semantic naming be produced in this session?
Reports whether the connected client supports host-LLM sampling (so the server needs no API key), whether a backend API key is configured as a fallback, and which method graphify_label_communities will pick.
Inputs: as_json. Returns: result
graphify_searchBRead-only
Search nodes by text in their name/label (case-insensitive).
Inputs: pattern (required), limit, as_json. Returns: result
graphify_subgraphARead-only
Extract a BFS subgraph around a node, capped at a token budget.
This is the token-cheap way to hand the model just the relevant slice of a large codebase instead of the whole graph.
Args: node: Center node (exact or fuzzy match). hops: BFS depth from the center. budget_tokens: Approximate cap on returned size; expansion stops when hit.
Inputs: node (required), hops, budget_tokens, as_json. Returns: result
graphify_surprisesCRead-only
List unexpected cross-file/cross-domain connections (surprise edges).
Inputs: limit, as_json. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
Each tool has a clearly distinct purpose: adding sources, building graphs, checking freshness, exploring nodes and paths, analyzing communities, and querying. There is no overlap between tool functionalities.
All tools use the 'graphify_' prefix followed by descriptive names. While some are verbs (e.g., graphify_build) and others nouns (e.g., graphify_communities), the pattern is consistent and names clearly indicate tool purpose.
With 16 tools, the server covers the core operations for knowledge graph management—building, adding sources, exploring, and analyzing—without being bloated. Each tool serves a clear need.
The tool set covers building, adding, exploring, querying, and community analysis. Missing are tools for deletion or modification of nodes/edges, but the surface is largely complete for the intended exploration and building workflow.
Maintenance
Related MCP Connectors
Repository knowledge graph MCP server for codebase understanding and debugging.
An MCP server that gives your AI access to the source code and docs of all public github repos
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that transforms codebases into knowledge graphs using Neo4J, enabling AI assistants to understand code structure, relationships, and metrics for more context-aware assistance.28MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that builds a knowledge graph from code and text documents, enabling Q\&A and implementation planning via tools like graph_create, graph_plan, and graph_query.7MIT
- FlicenseNot gradedqualityDmaintenanceAn in-memory knowledge graph MCP server that gives coding agents structural and semantic recall over codebases by indexing Python source, ADR documents, and project configuration, exposing 7 tools for search, traversal, context retrieval, and natural-language Q&A.-
- AlicenseNot gradedqualityCmaintenanceA universal MCP server providing persistent, structured memory through a knowledge graph with graph storage, semantic vector search, and multi-hop traversal for AI agents and IDEs.1MIT