Git Intelligence MCP Server

A lightweight Model Context Protocol (MCP) server that turns Git history into actionable repository insights.

<p align="center"> <img src="https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&logoColor=white" alt="Python"> <img src="https://img.shields.io/badge/MCP-Server-8A2BE2" alt="MCP Server"> <img src="https://img.shields.io/badge/GitPython-Supported-F05032?logo=git&logoColor=white" alt="GitPython"> <img src="https://img.shields.io/badge/Transport-stdio-4B5563" alt="stdio"> </p>

Overview

Git Intelligence MCP is a local MCP server that allows AI assistants to analyze Git repository history through natural-language requests.

Instead of manually running Git commands and interpreting commit history, an MCP-compatible client can call dedicated tools to discover:

• Frequently changed files
• Contributor ownership patterns
• Code churn over time

The project is intentionally lightweight and implemented in a single Python file using the official MCP Python SDK and GitPython.

---

Why Git Intelligence?

Git history contains useful engineering signals, but extracting them manually can be repetitive.

With Git Intelligence, you can ask questions such as:

"Which files have changed the most?"

"How many developers have worked on server.py?"

"How much code has changed since January 2026?"

The MCP server translates these natural-language requests into structured tool calls and analyzes the repository's Git history.

Natural Language
       │
       ▼
   MCP Client
       │
       ▼
Git Intelligence MCP
       │
   ┌───┼────────┐
   ▼   ▼        ▼
Hotspots  Bus Factor  Churn
   │   │        │
   └───┼────────┘
       ▼
 Git Repository
       │
       ▼
 Repository Insights

---

Features

Feature	Description
Hotspot Analysis	Finds files changed most frequently
Bus Factor Analysis	Counts distinct contributors for a file
Code Churn Analysis	Calculates lines added and removed since a date
Natural-Language Access	Allows AI clients to invoke Git analysis tools
Local Repository Support	Works directly with cloned Git repositories
Lightweight Architecture	No database or external service required
MCP Inspector Support	Easy local tool testing and debugging
VS Code Support	Can be connected directly to VS Code as an MCP client

---

Available MCP Tools

1. hotspots

Identifies the files that have been changed most frequently throughout the repository's commit history.

Arguments

Argument	Type	Default	Description
repo_path	string	Required	Path to the local Git repository
top_n	integer	10	Number of files to return

Example prompt

Use Git Intelligence to find the top 5 hotspot files in this repository.

Example tool call

hotspots(
    repo_path="E:/projects/my-repo",
    top_n=5
)

Example result

42 commits — server.py
27 commits — README.md
18 commits — config.py
12 commits — utils.py
9 commits — tests/test_server.py

A frequently modified file can be a useful signal for identifying areas that may deserve additional review or testing.

---

2. bus_factor

Determines how many distinct contributors have modified a specific file.

Arguments

Argument	Type	Description
repo_path	string	Path to the local Git repository
file_path	string	File to analyze

Example prompt

Use Git Intelligence to find how many developers have modified server.py.

Example tool call

bus_factor(
    repo_path="E:/projects/my-repo",
    file_path="server.py"
)

Example result

server.py: 3 distinct author(s) — Alice, Bob, Charlie

A low contributor count can indicate potential knowledge concentration around a particular file.

---

3. churn_since

Calculates the total number of lines added and removed since a specified date.

Arguments

Argument	Type	Description
repo_path	string	Path to the local Git repository
since_date	string	Start date in YYYY-MM-DD format

Example prompt

Use Git Intelligence to calculate the code churn since 2026-01-01.

Example tool call

churn_since(
    repo_path="E:/projects/my-repo",
    since_date="2026-01-01"
)

Example result

Since 2026-01-01: +842 / -391 lines

This provides a simple view of how much code has been added and removed during a given period.

---

Example Workflow

Once connected to an MCP-compatible client, you can interact with the repository using natural language.

Find repository hotspots

Use Git Intelligence to find the top 5 most frequently changed files.

↓

hotspots()

↓

Repository history

↓

Top 5 hotspot files

Investigate file ownership

How many different developers have worked on server.py?

↓

bus_factor()

↓

Distinct contributors

Analyze development activity

How many lines have been added and removed since 2026-06-01?

↓

churn_since()

↓

Code churn statistics

---

MCP Client Compatibility

The server uses stdio transport, making it suitable for local MCP-compatible clients.

It has been tested with:

• MCP Inspector — local development and tool testing
• VS Code — MCP client integration

The architecture remains simple:

┌───────────────────┐
│   MCP Client      │
│                   │
│ MCP Inspector     │
│ VS Code           │
└─────────┬─────────┘
          │
        stdio
          │
          ▼
┌───────────────────┐
│ Git Intelligence  │
│    MCP Server     │
├───────────────────┤
│ hotspots()        │
│ bus_factor()      │
│ churn_since()     │
└─────────┬─────────┘
          │
          ▼
┌───────────────────┐
│  Local Git Repo   │
└───────────────────┘

---

Demo

MCP Inspector

The MCP server was tested locally using MCP Inspector to verify tool discovery and execution.

VS Code Integration

The server was also connected to VS Code as an MCP client and its tools were successfully discovered.

---

Tech Stack

• Python 3.10+
• MCP Python SDK
• FastMCP
• GitPython
• Git
• stdio transport

The server uses the decorator-based FastMCP API to expose Python functions as MCP tools.

---

Project Structure

The project intentionally keeps the implementation minimal:

git-intel-mcp/
│
├── .vscode/
│   └── mcp.json
│
├── assets/
│
├── server.py
├── requirements.txt
├── README.md
└── .gitignore

Why a single server.py?

This project is designed as a focused MCP learning implementation rather than a large production application.

Keeping the core implementation in one file makes the MCP architecture easy to understand:

Define Tool
    ↓
@mcp.tool()
    ↓
MCP Tool Schema
    ↓
MCP Client
    ↓
Tool Call
    ↓
GitPython
    ↓
Git Repository
    ↓
Result

As the functionality grows, the tools can be separated into dedicated modules.

---

Installation

1. Clone the repository

git clone https://github.com/s-zaid-13/git-intel-mcp.git
cd git-intel-mcp

2. Create a virtual environment

Windows

python -m venv venv
venv\Scripts\activate

macOS / Linux

python -m venv venv
source venv/bin/activate

3. Install dependencies

pip install -r requirements.txt

---

Requirements

mcp[cli]<2.0.0
gitpython

---

Run Locally

Start the MCP server with:

python server.py

The server uses stdio transport, so it does not start a traditional web server.

It waits for an MCP-compatible client to establish a connection.

---

Test with MCP Inspector

MCP Inspector provides an interactive environment for testing MCP servers locally.

Run:

mcp dev server.py

Then:

1. Connect to the server
2. Inspect the available tools
3. Review their generated schemas
4. Provide arguments
5. Execute the tools
6. Verify the returned results

The following tools should be available:

hotspots
bus_factor
churn_since

---

Connect to VS Code

The MCP server can also be connected directly to VS Code.

Create:

.vscode/mcp.json

Example configuration for Windows:

{
  "servers": {
    "gitIntelligence": {
      "type": "stdio",
      "command": "E:\\Spiral Lab\\git-intel-mcp\\venv\\Scripts\\python.exe",
      "args": [
        "E:\\Spiral Lab\\git-intel-mcp\\server.py"
      ],
      "cwd": "E:\\Spiral Lab\\git-intel-mcp"
    }
  }
}

After connecting, the following MCP tools should be discoverable in VS Code:

gitIntelligence
├── hotspots
├── bus_factor
└── churn_since

Example request:

Use Git Intelligence to find the top 5 hotspot files in this repository.

---

How It Works

The server is built using FastMCP.

A tool is exposed using the MCP SDK decorator:

@mcp.tool()
def hotspots(repo_path: str, top_n: int = 10) -> str:
    ...

FastMCP uses the function signature and documentation to generate the tool definition that an MCP client can discover.

The complete flow is:

Python Function
      │
      ▼
@mcp.tool()
      │
      ▼
MCP Tool Definition
      │
      ▼
MCP Client
      │
      ▼
Tool Call
      │
      ▼
GitPython
      │
      ▼
Git History
      │
      ▼
Analysis Result

---

MCP Concepts Demonstrated

Tools

The server exposes three callable MCP tools:

hotspots
bus_factor
churn_since

These allow an AI client to perform repository analysis.

Client-Server Architecture

The MCP client does not need to know how the Git analysis is implemented internally.

It only needs to know:

• Which tools are available
• What arguments they accept
• What results they return

MCP Client
     │
     │ MCP
     ▼
MCP Server
     │
     ▼
Git Repository

stdio Transport

The local server communicates using stdio, which is well suited for locally running MCP servers and development clients.

---

Limitations

This implementation intentionally keeps the scope small.

• Only local Git repositories are supported.
• Large repositories may require additional processing time.
• Churn measures quantity of change, not code quality.

These limitations keep the project focused on understanding MCP rather than building a complete repository analytics platform.

---

Learning Outcome

This project demonstrates the fundamentals of building an MCP server with Python:

• Creating an MCP server with the official Python SDK
• Defining tools with FastMCP
• Understanding MCP tool schemas
• Using stdio transport
• Connecting an MCP server to MCP clients
• Testing tools with MCP Inspector
• Integrating a custom MCP with VS Code
• Preparing an MCP project for public sharing

The main takeaway is simple:

MCP provides a standardized way for AI applications to discover and interact with external tools and capabilities.

---

Author

Samama Zaid

Built as a hands-on project for learning and implementing the Model Context Protocol with Python.