codeatlas
This MCP server exposes a codeatlas knowledge graph so an agent can search and navigate a Python codebase structurally.
Search symbols by substring across symbol IDs and docstrings.
List symbols that call a given symbol for impact analysis.
List symbols called by a given symbol.
Show what a module imports and what imports it.
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., "@codeatlas who calls myapp.auth.login in my project?"
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.
codeatlas
Turn a Python codebase into a queryable knowledge graph — for AI agents and
for humans. Point codeatlas at a directory of .py files and it builds an
atlas: every module, class, and function as a node, and the imports,
inheritance, and calls between them as edges. Query the atlas from the
command line, render the module map as a Mermaid diagram, or serve it to an
LLM agent over MCP so the agent can answer "who calls this?" without reading
the whole repository.
Zero third-party dependencies. Python ≥ 3.10. The only parser is the standard
library's ast module — your code is analysed, never executed.
Quickstart
pip install .
codeatlas build path/to/project -o atlas.json
codeatlas stats atlas.json
codeatlas search atlas.json login
codeatlas query atlas.json myapp.auth.login --callers
codeatlas map atlas.json --out graph.mmd
codeatlas mcp atlas.json # serve the atlas to an agent over stdioNo-install use from a checkout:
PYTHONPATH=src python -m codeatlas build path/to/projectRelated MCP server: RepoGraph
What goes into the atlas
atlas.json is plain JSON, easy to diff, grep, or feed to other tools:
{
"nodes": [
{"id": "shop.orders.DiscountedOrder", "kind": "class",
"file": "shop/orders.py", "line": 14,
"docstring_first_line": "An order with a loyal-customer discount."}
],
"edges": [
{"src": "shop.orders", "dst": "shop.pricing", "kind": "imports"}
],
"stats": {"files": 3, "nodes": 9, "edges": 5,
"nodes_by_kind": {"class": 2, "function": 4, "module": 3},
"edges_by_kind": {"calls": 3, "imports": 1, "inherits": 1}}
}Node ids are dotted paths: package.module.Class.method. Node kinds are
module, class, and function (methods are functions under their class).
Edge kinds are imports, inherits, and calls.
Commands
Command | What it does |
| Scan a directory (or single file) and write the atlas |
| Show a symbol, or one relationship as a list |
| Substring search over symbol ids and docstrings |
| Mermaid flowchart of module-level imports |
| Files / nodes / edges, broken down by kind |
| Stdio MCP server (see below) |
Symbols in query do not need to be full ids: an exact id wins, then a
unique dotted suffix, then a simple name.
MCP server mode
codeatlas mcp atlas.json runs a small stdio JSON-RPC MCP server
(initialize, tools/list, tools/call) with four tools:
search_symbols— find symbols by substringcallers_of— who calls a symbolcallees_of— what a symbol callsmodule_deps— what a module imports, and what imports it
Wire it into any MCP-speaking agent and the agent can navigate the codebase structurally — impact analysis before an edit, orientation in an unfamiliar repository — instead of guessing from filenames.
How resolution works (honestly)
Static, name-based analysis has limits. codeatlas uses these heuristics:
Imports are linked only when the dotted path matches a scanned project module (relative imports are resolved against the importing package). Standard-library and third-party imports produce no edge. Imports are collected at module level, including inside top-level
if/tryblocks.Inheritance links a base class when a class with the same simple name (or a matching dotted suffix) exists in the project; a class from the same module wins.
Calls link when the called name matches a project function or method:
self.x()prefers a sibling method of the same class, a barename()prefers a function in the same module, and otherwise the first matching name in the project wins.
That means dynamic dispatch, getattr, decorators that replace functions,
and coincidental same-named helpers can produce missing or wrong call edges.
Treat the atlas as a good map of the territory — not the territory.
Self-scan
codeatlas, scanned with itself (codeatlas build src):
6 files, 51 nodes (6 modules, 2 classes, 43 functions), 64 edges (58 calls, 6 imports).
Development
PYTHONPATH=src python -m unittest discover -s tests24 tests cover the scanner (a fixture package with known imports, inheritance, and calls), the query layer, the CLI, Mermaid output, and an MCP round-trip driven through a subprocess.
What is included
src/codeatlas/scanner.py— directory walking andastextractionsrc/codeatlas/graph.py— theAtlasmodel, queries, stats, Mermaidsrc/codeatlas/cli.py— the six subcommandssrc/codeatlas/mcp_server.py— the stdio MCP serverexamples/demo_package/— a three-module package to try it on
Roadmap
Cross-file type-aware call resolution
HTML atlas viewer
Incremental rebuilds
License
MIT — see LICENSE.
Built with Muse
These tools were researched, built and published with Muse, a personal AI agent. Try it: https://muse.ai/join — redeem invite code IF2IUH in Settings within 48 hours of joining and we each get 1 billion Muse tokens.
Available Tools
4 toolscallees_ofC
List symbols called by the given symbol.
Inputs: symbol (required).
callers_ofC
List symbols that call the given symbol.
Inputs: symbol (required).
module_depsC
Show what a module imports and what imports it.
Inputs: module (required).
search_symbolsB
Search atlas symbols by substring over ids and docstrings.
Inputs: term (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool targets a distinct operation: substring search, incoming call edges, outgoing call edges, and module-level import edges. The only mild overlap is that callers_of and module_deps both answer 'what depends on this', but the symbol-vs-module scoping in the descriptions keeps them separable.
Three different naming patterns coexist: verb_noun (search_symbols), noun_of relations (callers_of, callees_of), and noun_noun (module_deps). Each name is readable and self-explanatory, but the set does not follow a single predictable convention.
Four tools is minimal but well-scoped for a symbol-graph lookup server; every tool covers a distinct query direction with no filler. It sits at the lean end of the acceptable range rather than feeling padded or arbitrarily thin.
The graph traversal surface is coherent (search, callers, callees, imports), but there is no way to fetch a symbol's details, signature, or location, and no file-level or reference-lookup operation. Agents can navigate the graph but will hit dead ends when they need the symbol itself.
Maintenance
Related MCP Connectors
Hosted code graph over MCP: exact callers, dependencies, and cross-repo blast radius for AI agents.
Ask a codebase what calls what: search, blast radius, paths between symbols, and diffs.
Codebase knowledge graph — architectural awareness for AI coding agents via MCP
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables AI coding agents to query a codebase as a knowledge graph, providing token-budgeted context, search, and impact analysis via MCP tools.27 PyPIMIT
- FlicenseNot gradedqualityCmaintenanceEnables coding agents to query a local-first code intelligence graph of Python repositories—covering functions, classes, modules, and their relationships—via MCP, supporting subgraph retrieval, caller lookup, and impact analysis without re-reading the codebase.-
- AlicenseNot gradedqualityCmaintenanceEnables AI coding agents to query a local, continuously updated symbol graph of a codebase, providing ranked search, caller/callee exploration, dependency paths, and git-diff impact analysis through MCP tools.14 npmApache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables coding agents to query a local, multi-repo code graph for symbol exploration, blast radius analysis, co-change mining, and durable code-anchored memory via MCP tools.128 npm16Business Source 1.1