Skip to main content

importlens-mcp

PyPI version License: MIT CI

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 own ast.

demo


Install

# run straight from PyPI with uv — no install needed
uvx importlens-mcp@latest

# or pip
pip install importlens-mcp

Add it to your agent. For Claude Code (user-wide):

claude mcp add --scope user importlens-mcp -- uvx importlens-mcp@latest

For any MCP client, point it at the importlens-mcp command (stdio transport). It indexes the current working directory by default, or set IMPORTLENS_ROOT.

What your agent gets

Four tools, all returning plain readable text:

tool what it does
project_map one-glance summary: files, modules, symbols, line count
relevant_files(symbol) the files that define a symbol + its dependents + its dependencies
file_context(path) one file's source plus the paths of its local imports
reindex 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 RiskManager
importlens-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

  1. Walk the repo, skipping the usual noise (.venv, node_modules, __pycache__, …).
  2. Parse each .py file with the standard-library ast module — top-level functions/classes become symbols, import statements become edges.
  3. Build two maps: symbol -> files that define it and module -> files that import it.
  4. 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 .py file (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 RiskManager 7,504 7,201 911 839 +8%
trading-bot TradingBot 7,504 7,201 1,138 1,675 −47%
trading-bot BacktestEngine 7,504 7,201 1,557 1,930 −24%
httpx DigestAuth 71,089 53,965 3,017 6,706 −122%
httpx Timeout 71,089 61,102 3,045 6,256 −105%
httpx MultipartStream 71,089 9,436 2,603 2,952 −13%
httpx Client 71,089 65,077 17,514 24,190 −38%
httpx Request 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 .gitignore
  • method-level symbols, not just top-level
  • tree-sitter backend 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.

License

MIT

Metadata

Release files for importlens-mcp 0.3.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for importlens-mcp 0.3.1
File Size Uploaded Provenance Actions
importlens_mcp-0.3.1.tar.gz 267.8 kB Without provenance Details for importlens_mcp-0.3.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for importlens-mcp 0.3.1
File Interpreter ABI Platform Actions
importlens_mcp-0.3.1-py3-none-any.whl Python 3 none any Details for importlens_mcp-0.3.1-py3-none-any.whl

Total release size: 280.0 kB

Release files / importlens_mcp-0.3.1.tar.gz

Download URL importlens_mcp-0.3.1.tar.gz
Size 267.8 kB
Tags Source
SHA-256 checksum
How to use checksums
474efe778c4b01aa4b16888781009de5baf97f86b1a963cfe35887402c9d9103
BLAKE2b-256 checksum
How to use checksums
4ab147dfb8857f5e2490648b6ff4c42384cfc736e3fa60bd46f3d553f8835ab5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.13

Release files / importlens_mcp-0.3.1-py3-none-any.whl

Download URL importlens_mcp-0.3.1-py3-none-any.whl
Size 12.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d5422f1fe84851fe108cc8665fe47d8e473ec7da2eae172a5a90c04016c75651
BLAKE2b-256 checksum
How to use checksums
83fe8067621737dead03a3bddce1240d750a868c0059d2e7486f8563ce577b82
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.13

Security for importlens-mcp 0.3.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page