Skip to main content

importlens-mcp

PyPI version License: MIT

Stop feeding your coding agent the whole repo. Feed it the files that actually matter.

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.

npx-style one-liner for python:  uvx importlens-mcp

Why: on a big repo, agents burn tokens (and get confused) re-reading files that have nothing to do with the task. importlens-mcp answers "which files matter for UserService?" in one call, using nothing but Python's own ast.

demo


Install

# with uv (recommended)
uvx importlens-mcp            # run straight from PyPI, no install

# or pip
pip install importlens-mcp

Add it to your agent. For(what I use) Claude Code:

claude mcp add importlens-mcp -- uvx importlens-mcp

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
- src/importlens_mcp/server.py

## Depends on (local imports)
- (none)

Three files instead of thirty. That's the whole idea.

Quick look without an agent

importlens-mcp map .
importlens-mcp: 4 files, 4 modules, 10 symbols, 371 lines
  importlens_mcp           src/importlens_mcp/__init__.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

Three strategies compared on two real repos. Token estimate: len(source) // 4.

  • all files — every source .py file (worst-case baseline)
  • grep baseline — files whose text contains the symbol name, plus their direct local imports (what an agent actually does: grep for the name, read those files and their deps)
  • importlens — only the files relevant_files() returns: defining file + local imports + dependents
repo symbol all files grep baseline importlens % saved vs grep
trading-bot RiskManager 8,187 7,884 5,255 +33%
trading-bot TradingBot 8,187 7,884 4,794 +39%
trading-bot BacktestEngine 8,187 7,884 4,625 +41%
httpx DigestAuth 71,089 53,965 36,062 +33%
httpx Timeout 71,089 61,102 42,838 +30%
httpx MultipartStream 71,089 9,436 18,487 −96%
httpx Client 71,089 65,077 58,993 +9%
httpx Request 71,089 66,452 66,357 +0%

Where importlens wins: symbols with a clear dependency boundary (DigestAuth, Timeout, RiskManager) — it prunes noise that grep can't. Where it doesn't: Client and Request are imported by almost every file, so both strategies converge on most of the codebase. MultipartStream is the inverse case: importlens tracks dependents (files that import it), pulling in the large _client.py; grep, which only matches the literal name, is cheaper here.

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 ~370 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.1.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.1.1
File Size Uploaded Provenance Actions
importlens_mcp-0.1.1.tar.gz 135.6 kB Without provenance Details for importlens_mcp-0.1.1.tar.gz

Built distribution (wheel)

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

Total release size: 145.7 kB

Release files / importlens_mcp-0.1.1.tar.gz

Download URL importlens_mcp-0.1.1.tar.gz
Size 135.6 kB
Tags Source
SHA-256 checksum
How to use checksums
61c24f928d26d80101b76074b7cae47ad3da324cfd0fcfb23288a6a561329008
BLAKE2b-256 checksum
How to use checksums
9b7b85bad19b63f9753fa89546d634d3df1b231b998f3b3f2b92aca078a5e675
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.1.1-py3-none-any.whl

Download URL importlens_mcp-0.1.1-py3-none-any.whl
Size 10.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e68f638b3e8eb1ee9df89b30b48dae27916a5fc785628652695eb214e86c7c5f
BLAKE2b-256 checksum
How to use checksums
6d31bf254dd65853789a50182d7222d710fcec8802be5baf2d600a4814152432
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.1.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