mcp-git-historian

# mcp-git-historian

MCP server for git archaeology — churn hotspots, blame summaries, bus factor, commit forensics and file history over any local repository.

Why

Every codebase carries answers to the questions that matter most during maintenance: Which files keep breaking? Who actually knows this legacy module? When did this weird constant appear? What happens if that one developer leaves? The answers are buried in git history, but digging them out means chaining log, blame, shortlog and pickaxe invocations with arcane flags — so nobody does it.

mcp-git-historian gives your AI assistant those forensic tools directly. It shells out to the git CLI you already have (no extra dependencies, no network calls, nothing leaves your machine) and returns structured, LLM-friendly summaries: hotspot rankings, ownership percentages, knowledge silos, and the exact commit where a piece of code first showed up.

Related MCP server: Git Stuff Server

Tools

How it works

flowchart LR
    A[Claude / MCP client] -->|tool call| B[server.py<br/>FastMCP wiring]
    B --> C[core.py<br/>pure stdlib logic]
    C -->|subprocess, 30s timeout| D[git -C repo_path<br/>log / blame / ls-files]
    D --> E[(local git repository)]
    D -->|"porcelain output<br/>(pretty %x1f/%x1e, numstat,<br/>blame --line-porcelain)"| C
    C -->|structured dict| B
    B -->|JSON result| A

All parsing relies on machine-friendly git output: custom --pretty formats with ASCII unit/record separators (%x1f/%x1e), --numstat for line churn, and blame --line-porcelain for ownership. Everything runs locally against repositories on your disk.

Quickstart

pip install -e .

Requires Python 3.10+ and the git CLI on your PATH.

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "git-historian": {
      "command": "python",
      "args": ["/absolute/path/to/mcp-git-historian/server.py"]
    }
  }
}

Claude Code:

claude mcp add git-historian -- python /absolute/path/to/mcp-git-historian/server.py

Example session

User: Nobody on the team dares to touch legacy/parser.py. Who actually knows that module, and how risky is it?

Claude: (calls blame_summary(repo_path="/work/acme-api", file="legacy/parser.py"))

Ownership is extremely concentrated: Alice Dev wrote 94.6% of the surviving lines (Bob Ops has the remaining 5.4%). The oldest line dates to 2019-03-11 and the newest to 2024-08-02 — it is old code, but still being touched.

(calls bus_factor(repo_path="/work/acme-api"))

The legacy/ directory is a knowledge silo: Alice authored 96.2% of all commits touching it. The repository's global bus factor is 2 — just two people account for more than half of all commits. If Alice is unavailable, legacy/ has no realistic second owner.

User: And where did that MAGIC_TOKEN constant in the parser even come from?

Claude: (calls find_change(repo_path="/work/acme-api", pattern="MAGIC_TOKEN", file="legacy/parser.py"))

The pickaxe found exactly one commit that introduced it: a1b2c3d (2019-04-02, Alice Dev) — "feat: add legacy parser handshake token". It has never been removed or re-added since, so that constant has survived untouched for years. I'd recommend pairing someone with Alice on the next legacy/ change and starting with tests around parse().

Development

pip install -e ".[dev]"
python -m pytest

The test suite builds a real throwaway git repository (two authors, a rename, a deleted file, pinned commit dates) and never imports mcp, so it runs with plain pytest.

License

MIT — see LICENSE.