repo-reader-mcp

A read-only MCP server that lets any AI agent read and search code in git repositories — files at any branch, tag or commit, the history, diffs, blame and search across many repositories — without ever changing them.

Status: pre-alpha. It reads local repositories, and remote ones it mirrors from any git host — one by one, or a whole group by a pattern (github: acme/shop-*) — at any branch, tag or commit: history, diffs, blame. One server can serve a team over HTTP behind a token, and search across all its repositories at once; secrets found in files are hidden. Documentation: rrm.pipelab.dev. The plan is in dev/PLAN.md, the design in dev/DESIGN.md.

Install

uvx repo-reader-mcp --config config.yaml --check   # with uv: nothing else to install
pip install repo-reader-mcp                          # or into an environment of your own
docker run --read-only --tmpfs /tmp -v "$PWD/config:/config:ro" -v repo-mirrors:/data -e REPO_READER_MCP_TOKEN \
  -p 8000:8000 ghcr.io/alexeiveselov92/repo-reader-mcp:0.2.0   # or its image, over HTTP

Python 3.12+ and git 2.31+; the image holds both (running it in a container). Then say which repositories it reads and connect your agent.

Why

Agents answer questions about code better when they can read it the way a developer does: open a file at the commit that matters, follow a change through the history, compare a branch with main, see who wrote a line and why. Most git MCP servers work on one local checkout and can write to it. This one is built to be pointed at many repositories — local folders or remote hosts — and to be safe to hand to a whole team.

What it will do

• Read a file, a folder, any branch, tag or commit — not only the default branch.
• History: commits of a repository or a path, a commit with its diff, a diff between two refs, blame.
• Guidance for agents: a repository's AGENTS.md, CLAUDE.md, rules and skills reach the agent reading it — plus what the people who run the server add, from its configuration or from another repository.
• Search across all configured repositories at once, and grep inside one at any ref, with lines of context.
• Any code host: local paths, GitHub, GitLab, Bitbucket, any git server — mirrored on a schedule, fetching only what is served; a group of repositories named by a pattern, new ones joining as they are created.
• Read-only by construction: no command that writes, no shell; secrets found in files are hidden before an agent sees them; answers sized for what clients accept.
• Any MCP client: stdio for a local agent, Streamable HTTP for a shared server — Claude, ChatGPT, Cursor, Codex, any client that speaks MCP.

Configuration

One YAML file names the repositories and what to take from them; secrets are named, never written in it. An example is in examples/config.example.yaml; every key is in docs/reference/configuration.md. The documentation is at rrm.pipelab.dev, built from docs/.

Development

Python 3.12, uv, the official MCP Python SDK.

uv sync
uv run pytest
uv run ruff check . && uv run ruff format --check .
uv run repo-reader-mcp --config my-config.yaml --check                 # check a configuration
uv run repo-reader-mcp --config my-config.yaml --sync                  # bring the mirrors up to date once
uv run repo-reader-mcp --config my-config.yaml                         # the server over stdio
uv run repo-reader-mcp --config my-config.yaml --http 127.0.0.1:8000   # over Streamable HTTP, at /mcp

License

Apache-2.0.