github-repo-mcp: letting an AI explore any GitHub repo without cloning it by hand

Posted on Oct 22 • Originally published at aniq-haider.vercel.app

When an assistant needs to understand a codebase it does not have locally, the usual options are pasting files or cloning by hand. I wanted something better: point the assistant at owner/repo and let it explore, the way a developer would. So I wrote github-repo-mcp, a local Model Context Protocol server.

The server runs over stdio. Repos are cloned once and reused from a local cache.

REQUEST PATH Claude (MCP client) ──▶ github-repo-mcp (stdio server, written in TypeScript on Bun) ──▶ Local clone cache (~/.cache/github-repo-mcp/owner/repo) ──▶ GitHub (Cloned once, pulled on refresh) FIVE TOOLS load_repo (Clone or reuse, return a summary) ──▶ get_repo_map (Files and exported symbols) ──▶ grep (Regex search with context) ──▶ read_file (A file or a line range) ──▶ refresh_repo (Pull latest, invalidate the map) Enter fullscreen mode Exit fullscreen mode How it works load_repo clones a repo (or reuses the cached copy) and returns languages, file count, a top-level tree and a README excerpt, enough to decide where to look next. get_repo_map builds a structural map of paths and exported symbols. TypeScript gets a fast extraction path, and other languages such as Python are parsed with tree-sitter. grep uses ripgrep for speed and falls back to a pure-JS search when ripgrep is not installed. A GitHub token is optional and only needed for private repos.

Path guards keep reads inside the cloned repo. The workflow it enables Load the repo, read the map to find the right module, grep for the call sites, then read only the lines that matter. The assistant spends its context on understanding the code and not on scrolling through it.

It is a small server with a deliberately small surface: five tools, one cache directory, and tests around the guards and the parser.