git-context-mcp

A local Model Context Protocol (MCP) server that provides structured, high-signal insight into a Git repository, enabling AI coding agents to understand project state, structure, activity, and risk — without uploading or modifying the codebase.

Note
This README was generated using git-context-mcp itself, by connecting an AI assistant to the repository through the exposed MCP tools.

Problem This Project Solves

AI coding agents (Claude Code, Cursor, Codex, Gemini, etc.) are powerful, but they lack situational awareness when working with non-trivial codebases.

They often struggle to answer questions like:

• What is the current state of this project?
• Where are the real entry points?
• What parts of the code are actively changing?
• Which files are risky to touch?

git-context-mcp solves this by turning Git history and repository structure into explicit, machine-readable context that AI agents can consume before writing or reviewing code.

What This MCP Does (and Does Not)

What it does

• Runs locally as a standalone MCP process
• Reads only Git metadata and repository files
• Exposes read-only analysis tools
• Works over STDIO (compatible with MCP Inspector and desktop coding agents)
• Provides high-level context, not raw source dumps

What it does not do

• Does not modify the repository
• Does not upload code anywhere
• Does not execute project code
• Does not depend on external services or APIs

Overview

git-context-mcp is a local-first MCP server focused on development context extraction, not repository manipulation.

It exposes Git-based analysis tools that help AI coding agents quickly understand:

• Repository structure and entry points
• Current working state and sync status
• Recent development activity and churn
• Technical debt indicators (TODO / FIXME)
• Files with elevated maintenance or bug risk

Typical Usage Flow

1. project_status – understand branch, cleanliness, and sync state
2. code_map – locate entry points and important modules
3. recent_activity – identify active or volatile areas
4. work_summary – understand recent work and open debt
5. risk_scan – flag risky files before editing

Features

project_status

Snapshot of the current Git repository state.

code_map

Structured directory tree with identification of important files.

recent_activity

Analysis of Git history to surface frequently modified files.

work_summary

High-level summary of recent development and technical debt.

risk_scan

Detection of large, complex, or high-churn files.

Requirements

• Python 3.10+
• Git installed and available on PATH
• A local Git repository to analyze

Installation

git clone https://github.com/TamiShaks-2/git-context-mcp.git
cd git-context-mcp

python -m venv .venv
source .venv/bin/activate   # macOS / Linux
# or
.venv\Scripts\activate    # Windows

pip install -e .

Running with MCP Inspector

Transport Type: STDIO

Command:

<path-to-venv>/python

Arguments:

src/server.py

Available MCP Tools

All tools operate in read-only mode.

Project Structure

git-context-mcp/
├── src/
│   ├── tools/
│   │   ├── code_map.py
│   │   ├── git_activity.py
│   │   ├── git_ops.py
│   │   ├── project_status.py
│   │   ├── risk_scan.py
│   │   └── work_summary.py
│   └── server.py
├── tests/
├── pyproject.toml
└── README.md

Testing

pytest

License

MIT License