importlens-mcp
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., "@importlens-mcp which files matter for the UserService class?"
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.
importlens-mcp
Give your coding agent the right slice of a Python repo in one call.
importlens-mcp is a tiny MCP server that reads your Python project's import graph and hands your agent only the slice of code relevant to what it's working on — the file that defines a symbol, the files that use it, and the files it depends on. No embeddings, no vector DB, no re-reading the tree on every question.
Why: when an agent needs to understand or change a symbol, it needs the defining file, the call sites that use it, and the interfaces of its dependencies — not the whole repo. importlens-mcp answers "which files matter for
RiskManager?" in one call, returning exactly that slice using nothing but Python's ownast.

Install
# run straight from PyPI with uv — no install needed
uvx importlens-mcp@latest
# or pip
pip install importlens-mcpAdd it to your agent. For Claude Code (user-wide):
claude mcp add --scope user importlens-mcp -- uvx importlens-mcp@latestFor any MCP client, point it at the importlens-mcp command (stdio transport). It indexes the current working directory by default, or set IMPORTLENS_ROOT.
Related MCP server: oxcode
What your agent gets
Four tools, all returning plain readable text:
tool | what it does |
| one-glance summary: files, modules, symbols, line count |
| the files that define a symbol + its dependents + its dependencies |
| one file's source plus the paths of its local imports |
| rebuild after you change files on disk |
Example
Ask your agent "how does CodeIndex fit together?" and under the hood it calls:
relevant_files("CodeIndex")# Relevant files for `CodeIndex`
## Defined in
- src/importlens_mcp/graph.py
## Used by (dependents)
### src/importlens_mcp/__main__.py
```python
1 from importlens_mcp.graph import CodeIndex, call_sites
...
22 idx = CodeIndex(str(root)).build()
23 s = idx.stats()
24 ...src/importlens_mcp/server.py
1 from .graph import CodeIndex, call_sites
...
34 _index = CodeIndex(_ROOT).build()Depends on (local imports)
(none)
Dependents show only the lines that use the symbol (+ a few lines of context), not the whole file. Pass `include_full_dependents=True` to get file paths instead.
## Quick look without an agent
```bash
importlens-mcp map .
importlens-mcp relevant RiskManagerimportlens-mcp: 6 files, 6 modules, 51 symbols, 1021 lines
importlens_mcp src/importlens_mcp/__init__.py
importlens_mcp.__main__ src/importlens_mcp/__main__.py
importlens_mcp.graph src/importlens_mcp/graph.py
importlens_mcp.server src/importlens_mcp/server.py
...How it works
Walk the repo, skipping the usual noise (
.venv,node_modules,__pycache__, …).Parse each
.pyfile with the standard-libraryastmodule — top-level functions/classes become symbols,importstatements become edges.Build two maps:
symbol -> files that define itandmodule -> files that import it.Answer queries by walking those maps. No network, no model calls, runs in milliseconds.
Import resolution is best-effort and handles src/ layouts and relative imports. It won't catch dynamic imports or runtime magic — and that's a fine tradeoff for a v0.
Benchmark
Four strategies compared on two real repos. Token estimate: len(source) // 4.
all files — every source
.pyfile (worst-case baseline)grep full files — files whose text contains the symbol name, plus their direct local imports, all read in full (naive agent behaviour)
grep -C3 — fairer smart-grep baseline: defining file read in full, every other mentioning file as a 3-line-context snippet
importlens — what
relevant_files()returns: defining file in full, local imports as signatures (def/class lines + first docstring line, no bodies), dependent files as call-site snippets
repo | symbol | all files | grep full files | grep -C3 | importlens | % saved vs grep -C3 |
trading-bot |
| 7,504 | 7,201 | 911 | 839 | +8% |
trading-bot |
| 7,504 | 7,201 | 1,138 | 1,675 | −47% |
trading-bot |
| 7,504 | 7,201 | 1,557 | 1,930 | −24% |
httpx |
| 71,089 | 53,965 | 3,017 | 6,706 | −122% |
httpx |
| 71,089 | 61,102 | 3,045 | 6,256 | −105% |
httpx |
| 71,089 | 9,436 | 2,603 | 2,952 | −13% |
httpx |
| 71,089 | 65,077 | 17,514 | 24,190 | −38% |
httpx |
| 71,089 | 66,452 | 16,113 | 18,729 | −16% |
Honest take: switching local imports from full files to signatures (v0.3) cut the gap dramatically — MultipartStream went from −108% to −13%, Request from −110% to −16%, and the trading-bot symbols are now within striking distance of grep -C3. Importlens still costs more tokens on most symbols because it insists on the full defining file while grep -C3 only shows snippets of it too.
That tradeoff is intentional: signatures give your agent the full interface of every dependency (what methods exist, what they accept, what they return) without the implementation noise. Grep -C3 gives you fragments — enough to locate something, not enough to safely change it. RiskManager wins outright; MultipartStream and Request are essentially ties. The remaining gap on DigestAuth and Timeout comes from their defining files having large local import chains that contribute substantial signatures.
Rerun with python benchmarks/bench.py (httpx needs git clone --depth=1 https://github.com/encode/httpx /tmp/httpx first).
Roadmap
call-graph edges (who calls this function), not just imports
respect
.gitignoremethod-level symbols, not just top-level
tree-sitterbackend for speed on huge repos
Contributing
It's ~530 lines of plain Python. Read it, break it, send a PR. Good first issues are labeled.
Agent Benchmark
24 total runs (quick: 3 tasks × with/without = 6; full: 6 tasks × with/without × 2 = 24).
Per-task results
cat | task | description | with pass | w/o pass | Δ pass | with tokens | w/o tokens | with tools | w/o tools | with tok/pass | w/o tok/pass | % fetched body |
A |
| add commission_pct to RiskManager | 100% | 100% | 0 | 71,192 | 70,947 | 3 | 3 | 71,192 | 70,947 | — |
A |
| add trailing_stop_pct to RiskManager | 100% | 100% | 0 | 89,588 | 109,098 | 4 | 5 | 89,588 | 109,098 | — |
B |
| timestamp every PaperBroker fill | 100% | 100% | 0 | 185,512 | 227,404 | 12.5 | 11 | 185,512 | 227,404 | — |
B |
| max_trades cap on BacktestEngine | 100% | 100% | 0 | 227,374 | 180,585 | 22.5 | 17.5 | 227,374 | 180,585 | — |
C |
| stop-loss on candle.low + fill at stop price | 100% | 100% | 0 | 103,717 | 117,106 | 5 | 4.5 | 103,717 | 117,106 | 50% |
C |
| warmup period in run_sweep | 100% | 100% | 0 | 283,694 | 295,788 | 12.5 | 15.5 | 283,694 | 295,788 | 100% |
— | TOTAL | — | 12/12 | 12/12 | — | 961,076 (-4%) | 1,000,926 | — | — | — | — | — |
Category summary
category | with pass% | w/o pass% | with tokens (med) | w/o tokens (med) | % fetched body (C only) |
A – defining file | 100% | 100% | 80,390 | 90,022 | — |
B – call sites | 100% | 100% | 206,442 | 203,994 | — |
C – dep body | 100% | 100% | 193,706 | 206,446 | 75% |
tok/pass = total tokens across all runs ÷ number of passing runs (lower is better; ∞ if no run passed). % fetched body = fraction of with-importlens runs on category-C tasks where the agent called
file_contextorReadon the tracked dependency.
Note: small repo (~1.4k source lines), 2 runs per condition — differences under ~10% are within run-to-run noise. Token counts include cached input.
License
MIT
Available Tools
4 toolsfile_contextA
Return a file's source plus the paths of its local dependencies.
Use this to read one file with awareness of what it pulls in, without loading the whole project.
Args: path: repo-relative path, e.g. "src/importlens_mcp/server.py".
Inputs: path (required). Returns: result
project_mapA
Summarize the Python project: file count, modules, symbols, lines.
Call this first to understand the shape of the repo before drilling in.
Inputs: no named parameters. Returns: result
reindexA
Rebuild the index. Call after you've changed files on disk.
Inputs: no named parameters. Returns: result
relevant_filesA
Find the files that matter for a given symbol (function or class name).
Returns the file(s) that define it, the call sites in dependent files, and
signatures of the local modules they depend on. This is the slice of the repo
an agent needs to reason about symbol — usually a handful of files instead
of the whole tree.
Args: symbol: a top-level function or class name, e.g. "CodeIndex". include_source: if true, also inline the defining files' source. include_full_dependents: if true, list dependent file paths instead of inlining the call sites where the symbol is used. include_full_imports: if true, list local import paths instead of inlining their signatures.
Inputs: symbol (required), include_source, include_full_imports, include_full_dependents. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
The three read tools have separable entry points: project_map is a whole-repo summary, relevant_files is keyed by a symbol name, and file_context is keyed by a file path. relevant_files and file_context could be momentarily confused (both 'return the slice I need'), but the descriptions explicitly distinguish symbol-centric vs path-centric usage.
All names are lowercase snake_case and readable. Three are noun compounds (project_map, relevant_files, file_context) while reindex is a bare verb, so there's no uniform verb_noun pattern, but the style is internally coherent enough to predict new names.
Four tools is on the lean side but each covers a distinct entry point in a code-navigation workflow, and no tool is redundant. A read-only indexer arguably needs only this set, though one more capability (search) would round it out.
Overview, symbol drill-down, file read, and reindex cover the main lifecycle of index-then-explore, but there is no text/pattern search or symbol listing, so an agent cannot locate code when it doesn't already know the symbol or file name. That is a notable gap, workable around only via repeated file_context reads.
Maintenance
Related MCP Connectors
Ask a codebase what calls what: search, blast radius, paths between symbols, and diffs.
Ask who calls a route, what a change breaks or who reads a field, across a system's repos.
Give your AI agent a persistent map of your project's structure, dependencies, and bugs.
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Related MCP Servers
- FlicenseAqualityDmaintenanceEnables blast-radius enforcement for coding agents by building an AST call/dependency graph and injecting a symbol's callers into the agent's context at the moment it edits a file.13-
- AlicenseNot gradedqualityCmaintenanceEnables coding agents to navigate and query source code by providing context, symbols, and call graph information through a graph index.4MIT
- 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 gradedqualityBmaintenanceEnables symbol-level codebase retrieval, providing definitions and usages of symbols to agents without reading whole files.ISC