Skip to main content
Glama
alexeiveselov92

repo-reader-mcp

by alexeiveselov92
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

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.3.1   # 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.

Related MCP server: Sourceplane MCP

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; 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.

Available Tools

1 tool
aboutA
Read-only

What this server is and what it will offer. Call it to check the connection.

NameRequiredDescriptionDefault

No parameters

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered structurally. The description reinforces this implicitly as a diagnostic/connection-check call but adds no detail on what the response contains or how failures manifest, leaving modest added value.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with zero waste, and the identity statement is front-loaded ahead of the call-to-action. Nothing is padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description should ideally say what an agent gets back (server name, version, capabilities) so the tool's result can be reasoned about. It gestures at this with 'what this server is and what it will offer' but stops short of concrete return-value disclosure.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is no parameter semantics to explain; the baseline for a param-less tool applies. The description correctly does not fabricate any inputs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the tool returns information about the server and its offerings, but 'what it will offer' is vague about the actual content. There's no concrete verb+resource framing (e.g., 'returns server name, version, capabilities') and no siblings to differentiate from, so the purpose is only loosely established.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives an explicit trigger: 'Call it to check the connection.' With no sibling tools, there are no alternatives to exclude, so the usage context is clear enough for an agent to know when to invoke it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev0.0.1
    • First observedabout
Deploy Server
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

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

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • code-intel-mcp

    arunveersingh
    A
    license
    Not graded
    quality
    C
    maintenance
    MCP server that gives AI agents deep code understanding across multiple git repositories, combining git lifecycle management, Zoekt-based trigram code search, and cross-repo dependency analysis.
    16 PyPI
    MIT

  • Sourceplane MCP

    infraWS
    A
    license
    Not graded
    quality
    D
    maintenance
    Secure multi-source MCP server for reading local, GitHub, GitLab, Bitbucket, and network source code with read-only-by-default access, enabling AI assistants to inspect repositories safely.
    1
    MIT

  • github-assistant-mcp

    imshashwatsingh
    A
    license
    A
    quality
    C
    maintenance
    A read-only MCP server that lets AI assistants inspect local workspace files, search context, view git diffs, and fetch a fixed GitHub profile, all within a sandboxed stdio transport.
    5
    ISC

  • MCQuest MCP

    LionTechSupport
    F
    license
    A
    quality
    B
    maintenance
    A read-only MCP server that gives AI coding agents structured access to a project's source code, architecture, documentation, and Git context through 16 tools for searching, reading, and comparing evidence without modifying files.
    16
    -