Identifies the specific files and lines an AI agent needs to read for a coding task to reduce token usage.
Also known as jbacalso24/mimry
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- 2,522
- Latest version
- 0.9.0
- Last commit
- Nov 10, 2026
- License
- MIT
What is MIMRY MCP?
MIMRY identifies the specific files and lines an AI agent needs to read for a coding task to reduce token usage.
Summary generated from the project's README
About MIMRY MCP server
Reducing token consumption for AI coding agents is what MIMRY achieves by identifying the exact files and line ranges required for a specific task. It works by parsing a repository into a dependency graph of symbols, allowing an agent to read only the most relevant code rather than entire files. This process happens entirely on your local machine using tree-sitter to parse over 40 languages, including Python, JavaScript, Go, and SQL, as well as various documentation formats like Markdown and PDF.
Developers can integrate this tool into their workflow via a command-line interface or an MCP server. It supports a wide range of agents such as Claude Code, Cursor, and GitHub Copilot through specific installation commands. Because the indexing is deterministic and runs locally without an LLM or API keys, it provides consistent results across Windows, Linux, and macOS while maintaining privacy. The system even includes incremental indexing to ensure only changed files are re-processed.
What you can do with it
- 1Navigate complex code dependenciesA developer can ask the agent to find all functions that call a specific symbol within the project graph.
- 2Perform targeted code searchesYou can instruct an agent to rank files based on a plain-text description of a programming task.
- 3Analyze non-code project documentationThe tool can index and help an agent navigate through project manuals stored in PDF or Word formats.
Written from the project's README. Every use case is checked against a quote from it.
How to install MIMRY MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall MIMRY MCP in Claude Code
$ claude mcp add mimry -- uvx mimryInstall MIMRY MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mimry": {
"command": "uvx",
"args": [
"mimry"
]
}
}
}Install MIMRY MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mimry": {
"type": "stdio",
"command": "uvx",
"args": [
"mimry"
]
}
}
}Install MIMRY MCP in VS Code CLI
$ code --add-mcp '{"name":"mimry","type":"stdio","command":"uvx","args":["mimry"]}'Install MIMRY MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mimry": {
"command": "uvx",
"args": [
"mimry"
]
}
}
}Install MIMRY MCP in Codex
$ codex mcp add mimry -- uvx mimryInstall MIMRY MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mimry] command = "uvx" args = ["mimry"]
Install MIMRY MCP in Gemini CLI
$ gemini mcp add -s user mimry uvx -- mimryInstall MIMRY MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mimry": {
"command": "uvx",
"args": [
"mimry"
]
}
}
}Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work · What to fix for more points
- Source repository linked and reachablejbacalso24/mimry is public and reachablegithub.com/jbacalso24/mimry ↗Pass
- Package names this repository as its sourcemimry names https://github.com/jbacalso24 as its sourcepypi.org/project/mimry/ ↗Finding
- Build provenance (Sigstore attestation)Sigstore attestation for mimrypypi.org/project/mimry/ ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-10github.com/jbacalso24/mimry ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from mimryPass
- No critical advisory in the package or its dependencies4 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubMIMRY is a command-line tool that tells AI coding agents which files, and which lines in them, to read for a task. It parses a repository into symbols and a dependency graph, keeps the index on your machine, and ranks the files that matter for a task described in plain words. The index is deterministic: the same code gives the same graph, rankings and context pack on Windows, Linux and macOS, and no LLM is involved in building it. Agents call it from the shell or through its MCP server.
Installation
Get started in four steps.
-
Install uv, the tool that installs MIMRY. Pick the command for your system. macOS or Linux:
curl -LsSf https://astral.sh/uv/install.sh | shWindows, in PowerShell:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"Then open a new terminal. Already have uv? Skip this step. For other ways to install uv, see the uv installation guide.
-
Install MIMRY.
uv tool install mimryMIMRY needs Python 3.11 or newer on Windows, Linux or macOS. uv downloads a suitable Python itself if none is installed. If the shell says
mimryis not found, runuv tool update-shell, then open a new terminal. -
Connect your agent. This is what makes the agent use MIMRY on its own. Claude Code users pick one of these two, not both:
/plugin marketplace add jbacalso24/mimry /plugin install mimry@mimryor run
mimry install --platform claude-code. Other agents: runmimry install --platform <name>, see Supported agents.mimry install --platform claude-codealso adds MIMRY's hooks, which steer the agent to MIMRY and do nothing in folders MIMRY has not set up. Add--no-hooksto leave them out. With--project,--always-onalso adds MIMRY's rules to the agent's always-read file. -
Check it works. In a repository, run
mimry preflight "<a task in your own words>". The first run builds the index and downloads the tree-sitter grammars it needs, once per user. If something looks off, runmimry doctor.
[!NOTE] To upgrade, run
mimry upgrade. On Windows,mimry upgraderefuses while MIMRY servers run, andmimry upgrade --stop-serversstops them first.
Other ways to install
These replace steps 1 and 2, or add an optional feature.
- pipx or a venv
- Docker
- Claude Code plugin
- npx skills, for other agents, skill only
- Embeddings, for search by meaning
Quick start
Run mimry preflight in your repository with a task description.
The first run builds the index.
mimry preflight "Fix session cookie not refreshed when SESSION_REFRESH_EACH_REQUEST is set"
Output on the Flask repository:
Start with
1 src/flask/sessions.py
name matches · path matches · connected to other matches
read first: lines 202-206 (get_cookie_secure), 233-247 (should_set_cookie)
2 src/flask/ctx.py
name matches · connected to other matches
read first: lines 154-206 (copy_current_request_context), 395-403 (session)
3 src/flask/testing.py
name matches · connected to other matches
read first: lines 135-183 (session_transaction), 193-202 (_request_from_builder_args)
The same result is written to .mimry/mimry-out/context/latest.md as a context pack for the agent, with the matched symbols, related files and the project's test commands.
Prompt hook: Name the files for each task. Token savings: See the tokens MIMRY saved.
Features
- Ranked lookup. Ranks files and names the lines to read first in each.
- Code graph. Parses 41 languages with tree-sitter.
- Deterministic. Same code, same results on every machine (how).
- Documents. Indexes Markdown, PDF, Word, Excel and PowerPoint.
- Incremental. Re-reads only the files that changed.
- Feedback. Ranks files that helped on similar tasks higher.
- MCP server. Exposes every lookup as an MCP tool.
- Local. No LLM, API key or telemetry.
Supported languages
MIMRY parses these with tree-sitter.
| Area | File types | What MIMRY reads |
|---|---|---|
| Programming | .py, .js, .ts, .go, .java and more |
Symbols, imports, calls |
| Stylesheets | .css, .scss |
Selectors, variables, mixins |
| Markup | .html, .vue, .svelte |
Element ids and components |
| SQL | .sql |
Tables and the objects that use them |
| Data | .json, .yaml, .toml, .xml, .tf |
Keys and names, never values |
| Build files | .gradle, package.json, pyproject.toml |
Tasks, commands, entry points |
| Documents | .md, .pdf, .docx, .xlsx, .pptx |
Headings, pages, sheets, slides |
Every extension is in docs/languages.md.
Supported agents
mimry install --platform <name> installs a skill that teaches the agent when to use MIMRY, and registers the MCP server where the agent supports it.
| Agent | Platform name | Skill | MCP server |
|---|---|---|---|
| Claude Code | claude-code |
✅ | ✅ |
| Codex | codex |
✅ | ✅ |
| GitHub Copilot CLI | copilot |
✅ | ✅ |
| GitHub Copilot in VS Code | vscode |
✅ | ✅ |
| Gemini CLI | gemini |
✅ | ✅ |
| OpenCode | opencode |
✅ | ✅ |
| Kiro | kiro |
✅ | ✅ |
| Cursor | cursor |
✅ | ✅ |
| Amp | amp |
✅ | ✅ |
| Devin | devin |
✅ | ✅ |
| Factory Droid | droid |
✅ | ✅ |
| Kimi | kimi |
✅ | ✅ |
| Kilo Code | kilo |
✅ | manual |
| Antigravity, CodeBuddy, Hermes, OpenClaw, Trae | see mimry install --list-platforms |
✅ | manual |
| Trae CN | trae-cn |
✅ | manual |
| Aider, Pi Agent | see mimry install --list-platforms |
✅ | none |
| Agent Skills | agents |
✅ | none |
| Windsurf | windsurf |
✅ | manual |
| Cline | cline |
✅ | manual |
| Roo Code | roo |
✅ | manual |
| Zed | zed |
✅ | ✅, or printed to paste in when its settings file has comments |
| JetBrains Junie | junie |
✅ | ✅ |
| Grok Build | grok |
✅ | not yet |
✅ means mimry install sets it up, and manual means you add the MCP server by hand.
none means the agent has no MCP support, so the skill alone covers it.
not yet means mimry install does not register an MCP server for the agent yet.
Each agent's files, the install options and manual MCP setup are in docs/agents.md.
Usage
mimry preflight "<task>" # list the files and lines to read first, and write a context pack
mimry find "<query>" # rank files for a query
mimry symbol <name> # find where a function, class or heading is defined
mimry callers <name> # list the functions that call a function, from the graph
mimry callees <name> # list the functions a function calls, from the graph
mimry related "<query>" # list files connected through imports and calls
mimry explain "<task>" # show the key files and symbols, and how they connect
mimry why <file> --query "<task>" # explain why a file ranked
mimry feedback ... # record which files helped
mimry status # check whether the index is current
mimry doctor # diagnose the install and the index
See docs/commands.md for every command and option. When something misbehaves, see docs/troubleshooting.md.
Configuration
A mimry.toml at the repository root controls which files are indexed.
Commit it so everyone on the team gets the same index.
The options and examples are in docs/configuration.md.
Benchmarks
These numbers come from a scripted retrieval benchmark, not from complete agent sessions. Measured with MIMRY 0.9.0 on 44 merged pull requests from 6 open-source projects, the set rerun for every release:
| How the agent reads files | Tokens saved with MIMRY | Tasks located, MIMRY / grep |
|---|---|---|
| The line ranges MIMRY names first | 71.4% | 32 / 28 |
| Whole files | 51.0% | 33 / 28 |
grep -n, then 100 lines around each match |
48.6% | 31 / 27 |
Method, SWE-bench results and a worked example: docs/benchmarks.md.
How it works
MIMRY parses each file into symbols and edges, ranks files against a task, and re-reads only the files that changed. The three steps are described in docs/how-it-works.md.
Privacy
Indexing and search run locally. Credential files are skipped. The details, including how secrets are redacted, are in docs/privacy.md.
Contributing
Bug reports and pull requests are welcome. See CONTRIBUTING.md for setup and checks. MIMRY is in public alpha, and its interfaces may change before 1.0.
Thanks to everyone who has contributed:
License
MIMRY MCP questions
How do I add MIMRY MCP to Claude Code?
Run claude mcp add mimry -- uvx mimry in your terminal. Add --scope user to make it available in every project.
How do I add MIMRY MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How much can MIMRY save in tokens?
In a scripted retrieval benchmark, it can lead to 71% fewer tokens to reach the code a task changes.
Does MIMRY use an LLM to build its index?
No, the index is deterministic and no LLM is involved in the building process.
What programming languages does it support?
It parses 41 languages using tree-sitter, including Python, JavaScript, TypeScript, Go, and Java.