repo-reader-mcp
README.md
# repo-reader-mcp
A read-only [MCP](https://modelcontextprotocol.io) 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](https://rrm.pipelab.dev)**. The plan is in [dev/PLAN.md](https://github.com/alexeiveselov92/repo-reader-mcp/blob/main/dev/PLAN.md), the design in [dev/DESIGN.md](https://github.com/alexeiveselov92/repo-reader-mcp/blob/main/dev/DESIGN.md).
## Install
```bash
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.3.1 # or its image, over HTTP
```
Python 3.12+ and git 2.31+; the image holds both ([running it in a container](https://rrm.pipelab.dev/running-in-a-container/)). Then [say which repositories it reads and connect your agent](https://rrm.pipelab.dev/getting-started/).
## 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 — and
commits found by their message across every repository (a ticket's key, a pull request's number), each saying
when it reached the default branch and which releases have it.
- **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](https://github.com/alexeiveselov92/repo-reader-mcp/blob/main/examples/config.example.yaml); every key is in
[docs/reference/configuration.md](https://github.com/alexeiveselov92/repo-reader-mcp/blob/main/docs/reference/configuration.md). The documentation is at
**[rrm.pipelab.dev](https://rrm.pipelab.dev)**, built from [docs/](https://github.com/alexeiveselov92/repo-reader-mcp/blob/main/docs/README.md).
## Development
Python 3.12, [uv](https://docs.astral.sh/uv/), the official [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk).
```bash
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](https://github.com/alexeiveselov92/repo-reader-mcp/blob/main/LICENSE).
TDQS
B3.4/5.0
Scored across 1 tool
Disambiguation5/5
There is only one tool, so there is no risk of confusing it with another tool. Its purpose as a connection/about check is clear from its description.
Naming Consistency4/5
With a single tool there is no mixed naming convention to evaluate. However, 'about' is a noun and does not follow the common verb_noun pattern, so it is slightly less predictable.
Tool Count1/5
The server is named repo-reader-mcp, but it exposes only a single trivial 'about' tool. This is an extreme mismatch between the apparent purpose and the available tool surface.
Completeness1/5
There are no tools for reading repositories, files, metadata, or any core repo-reader functionality. The surface is severely incomplete for the stated purpose.
Maintenance
ActivityNo data
ResponsivenessOutdated data