GitIntel MCP Server

GitIntel - A Git Intelligence MCP Server for AI Agents

Git Intelligence MCP Server - deep repository analytics computed locally from your commit history.

Surfaces the same insights that tools like CodeScene and GitPrime charge for: hotspots, temporal coupling, knowledge maps, churn analysis, complexity trends, risk scoring, and more. Everything runs locally. No external APIs, no data leaves your machine.

This is a locally-built MCP server. It is not published to npm. You clone, build, and register it with your MCP client & AI agents (Claude Code, Codex, etc.).

You:    "Analyze this repo -- show me hotspots, risk, and who knows the auth module best."
Claude: [calls hotspots, risk_assessment, knowledge_map in parallel, returns formatted analysis]

---

Architecture

GitIntel is a standalone MCP server that exposes a suite of tools and resources for analyzing git repositories. It communicates with any MCP client (Claude Code, Codex, etc.) over stdio using JSON-RPC.

graph LR
    A[MCP ClientClaude Code / Codex] |stdioJSON-RPC| B[mcp-git-intelMCP Server]
    B -->|execFile| C[Git CLI]
    C --> D[Repository.git]
    B --> E[Analysis Enginescoring, formatting]

All communication happens over stdio using the Model Context Protocol. The server calls Git via execFile (never exec) to prevent shell injection. All operations are strictly read-only.

---

Tools

12 analysis tools, each returning formatted tables, score bars, and actionable recommendations -- not raw git output.

graph TD
    subgraph "Change Analysis"
        H[hotspotsChange frequency]
        CH[churnWrite/rewrite ratio]
        CT[complexity_trendComplexity over time]
    end
    subgraph "Dependency Analysis"
        CO[couplingTemporal coupling]
    end
    subgraph "Team Analysis"
        KM[knowledge_mapWho knows what]
        CS[contributor_statsTeam dynamics]
        CP[commit_patternsWork patterns]
    end
    subgraph "Risk & Release"
        RA[risk_assessmentChange risk scoring]
        RN[release_notesChangelog generation]
        BR[branch_riskBranch health]
    end
    subgraph "Code Archaeology"
        FH[file_historyFile evolution]
        CA[code_ageStaleness map]
    end

| Tool | What it does | Key insight | |------|-------------|-------------| | hotspots | Files that change most frequently | Top 4% of files by change frequency contain 50%+ of bugs | | churn | Code written then rewritten (additions vs deletions) | Churn ratio near 1.0 = code rewritten as fast as it's written | | coupling | Files that always change together | Hidden dependencies not visible in imports | | knowledge_map | Who knows a file/directory best, weighted by recency | Find the right reviewer, spot knowledge silos | | complexity_trend | How a file's complexity evolves over time | Catch files growing out of control | | risk_assessment | Risk score (0-100) for uncommitted or committed changes | Combines hotspot history, size, sensitivity, spread | | release_notes | Structured changelog from conventional commits | Groups by type, extracts breaking changes and PR refs | | contributor_stats | Team dynamics, collaboration graph, knowledge silos | Workload distribution, onboarding planning | | file_history | Full commit history of a single file with rename tracking | Trace why a file looks the way it does | | code_age | Age map showing when each file was last modified | Find dead code, abandoned features, stable infrastructure | | commit_patterns | Day-of-week, hour-of-day, commit size distributions | Spot weekend work, late-night hotfixes, oversized commits | | branch_risk | Branch staleness, divergence, and merge risk analysis | Branch hygiene, cleanup candidates, merge planning |

Data Pipeline

Each tool transforms raw git output through a multi-stage pipeline:

graph LR
    A["Git CLIraw output"] -->|parse| B["Structured DataLogEntry[], stats"]
    B -->|score| C["Scored Resultsnormalized 0-100"]
    C -->|format| D["Formatted Outputtables, bars, text"]
    D -->|wrap| E["MCP ResponseCallToolResult"]

Resources

Resources are pre-computed summaries or feeds that can be read directly without arguments. Useful for quick snapshots or embedding into prompts.

| Resource URI | Description | |-------------|-------------| | git://repo/summary | Repository snapshot: branch, last commit, total commits, active contributors, top languages, age, remote | | git://repo/activity | Recent 50-commit activity feed with stats |

---

Installation

This server is not published to npm. You must clone, build, and register it locally.

Prerequisites

• Node.js >= 18
• Git >= 2.20

Build from source

git clone https://github.com/hoangsonww/GitIntel-MCP-Server.git
cd GitIntel-MCP-Server
npm install
npm run build

Register with Claude Code

> [!IMPORTANT] > Important: For best results, always open Claude Code inside a git repository directory. The server auto-detects the repo from your working directory. If you open Claude Code from a non-repo folder (e.g. your home directory), you will need to pass repo_path to every tool call manually.

Quick registration (analyzes cwd by default):

claude mcp add git-intel -- node /absolute/path/to/mcp-server/dist/index.js

With a specific repository:

claude mcp add git-intel -- node /absolute/path/to/mcp-server/dist/index.js /path/to/your/repo

Register with any MCP client (manual JSON)

Add to your MCP client's configuration file (e.g. ~/.claude.json for Claude Code global config):

{
  "mcpServers": {
    "git-intel": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"],
      "env": {}
    }
  }
}

With a pinned default repository (optional — useful if you always analyze the same repo):

{
  "mcpServers": {
    "git-intel": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"],
      "env": {
        "GIT_INTEL_REPO": "/path/to/your/repo"
      }
    }
  }
}

> [!TIP] > Tip: The ~ home directory expansion works in the repo path argument (e.g. ~/projects/my-repo). > > Also: When registered globally (in ~/.claude.json), the server auto-detects the git repo in your current working directory. No GIT_INTEL_REPO needed — just open Claude Code inside any git repo.

---

Configuration

Default Repository Resolution

The server determines which git repository to use as the default using this priority order:

| Priority | Method | Example | |----------|--------|---------| | 1 | CLI argument | node dist/index.js /path/to/repo | | 2 | Environment variable | GIT_INTEL_REPO=/path/to/repo | | 3 | Current working directory | Falls back to process.cwd() |

The ~ prefix is expanded to the user's home directory in all path inputs.

Per-Tool repo_path Override

Every tool accepts an optional repo_path parameter that overrides the default repository for that specific call. This allows analyzing any repository on disk without reconfiguring the server:

{ "repo_path": "C:/Users/you/other-project", "days": 90 }

Resilient Startup (No-Crash Mode)

The server never crashes on startup, even when launched from a non-git directory. Instead:

1. If a git repository is found, it becomes the default for all tools.
2. If no git repository is found, the server starts anyway with no default repo. Tools require the repo_path parameter to specify which repo to analyze.
3. Resources (git://repo/summary, git://repo/activity) return informative messages directing the user to open Claude Code inside a git repo or use repo_path.

flowchart TD
    Start["Server starts"] --> CheckRepo{"Is cwd a\ngit repo?"}
    CheckRepo -->|Yes| Default["Set as default repo\nAll tools work immediately"]
    CheckRepo -->|No| NoDefault["Start with no default\nTools require repo_path"]
    Default --> Ready["Server ready\n12 tools, 2 resources"]
    NoDefault --> Ready
    Ready --> Call{"Tool called"}
    Call --> HasArg{"repo_path\nprovided?"}
    HasArg -->|Yes| UseArg["Use repo_path"]
    HasArg -->|No| HasDefault{"Default repo\navailable?"}
    HasDefault -->|Yes| UseDefault["Use default repo"]
    HasDefault -->|No| Error["Return helpful error:\n'Open Claude Code in a git repo\nor pass repo_path'"]
    UseArg --> Execute["Execute git analysis"]
    UseDefault --> Execute

This design means the server works as a global MCP server in Claude Code — it connects successfully regardless of which project directory you open.

---

Usage Examples

Once registered, the tools are available through natural language. You do not call them directly -- the AI client decides which tools to invoke based on your prompt.

Find bug-prone files: > "Show me the change hotspots in the last 60 days"

Analyze code stability: > "What's the churn analysis for the src/api directory over the last quarter?"

Find hidden dependencies: > "Which files are temporally coupled with src/auth/login.ts?"

Find the right reviewer: > "Who knows the src/api directory best?"

Track complexity growth: > "Show me the complexity trend for src/services/payment.ts"

Assess change risk before merging: > "What's the risk assessment for the uncommitted changes?" > "Assess the risk of changes between main and feature-branch"

Generate release notes: > "Generate release notes from v1.0.0 to HEAD"

Understand team dynamics: > "Show me contributor statistics for the last 6 months" > "Who are the top collaborators and where are the knowledge silos?"

Trace a file's evolution: > "Show me the full history of src/auth/login.ts"

Find stale or abandoned code: > "What are the oldest files in the src/ directory?" > "Show me code age analysis for the project"

Analyze work patterns: > "What are the commit patterns for the last 3 months?" > "When does the team usually commit?"

Branch hygiene: > "Which branches are stale or highly diverged?" > "Show me branch risk analysis against main"

Full repo analysis: > "Using git-intel, give me a comprehensive analysis of this repository"

See [docs/EXAMPLES.md](docs/EXAMPLES.md) for a complete real-world transcript of a full repo analysis session.

---

Development

graph LR
    subgraph "Development"
        Dev["npm run devtsx auto-reload"]
        CLI["npm run cliInteractive REPL"]
    end
    subgraph "Testing"
        Unit["npm testVitest unit tests"]
        Smoke["npm run smokeFull integration"]
    end
    subgraph "Quality"
        Lint["npm run linttsc --noEmit"]
        Fmt["npm run formatPrettier"]
    end
    subgraph "Ship"
        Build["npm run buildTypeScript → dist/"]
    end

    Dev --> Unit --> Lint --> Build
    CLI --> Smoke

npm run dev          # Run server with tsx (auto-reload, uses cwd as repo)
npm run cli          # Interactive REPL for testing tools and resources
npm run smoke        # Automated smoke test -- runs every tool and resource
npm test             # Run unit tests (vitest)
npm run test:watch   # Watch mode
npm run lint         # Type check (tsc --noEmit)
npm run build        # Compile TypeScript to dist/

CLI REPL

The interactive CLI (npm run cli) spawns the MCP server as a child process, connects as a real MCP client over stdio, and provides a REPL for calling tools and reading resources.

sequenceDiagram
    participant User as Developer
    participant CLI as cli.ts (MCP Client)
    participant Server as index.ts (MCP Server)
    participant Git as Git CLI

    User->>CLI: npm run cli [repo_path]
    CLI->>Server: Spawn via StdioClientTransport
    Server-->>CLI: Connected (JSON-RPC over stdio)
    CLI->>User: git-intel> prompt

    User->>CLI: call hotspots {"days": 60}
    CLI->>Server: callTool("hotspots", {days: 60})
    Server->>Git: git log --since=...
    Git-->>Server: raw output
    Server-->>CLI: formatted analysis
    CLI->>User: Display result + elapsed time

    User->>CLI: read git://repo/summary
    CLI->>Server: readResource("git://repo/summary")
    Server-->>CLI: repo snapshot
    CLI->>User: Display result

    User->>CLI: exit
    CLI->>Server: close()

Start the CLI:

npm run cli                    # Uses current directory as repo
npm run cli ~/projects/myapp   # Analyze a specific repo

Available commands:

| Command | Description | |---------|-------------| | tools | List all registered tools with parameters | | resources | List all registered resources | | call [json] | Call a tool with optional JSON arguments | | read | Read a resource by URI | | help | Show help | | exit / quit / q | Quit the CLI |

Example session:

git-intel> tools
  Available tools (12):
  hotspots               Identify files that change most frequently...
                         params: repo_path, days, limit, path_filter
  churn                  Analyze code churn...
                         params: repo_path, days, limit, path_filter
  ...

git-intel> call hotspots {"days": 60, "limit": 5}
  Calling hotspots...
  (42ms)

## Change Hotspots (last 60 days)
File                  Changes  Authors  Last Changed  Heat
--------------------  -------  -------  ------------  ---------------
src/index.ts               12        2    2026-03-08  [██████████] 100
src/tools/risk.ts           8        1    2026-03-07  [██████░░░░] 67
...

git-intel> call knowledge_map {"path": "src/auth"}
  Calling knowledge_map...
  (38ms)

## Knowledge Map: src/auth (last 365 days)
...

git-intel> call risk_assessment
  Calling risk_assessment...
  (125ms)

## Risk Assessment: uncommitted changes
...

git-intel> read git://repo/summary
  Reading git://repo/summary...
  (15ms)

Branch: master
Last commit: c4934239 by dav nguyxn on 2026-03-09
...

git-intel> exit
Bye.

See [docs/CLI.md](docs/CLI.md) for the full CLI reference.

> [!TIP] > This is useful for manual testing and debugging without needing to go through an AI client.

Smoke Test

npm run smoke connects to the server and calls every tool and every resource against the current repo, printing all results. Useful for verifying nothing is broken after changes.

---

Security Model

graph LR
    Input["User / AI Input"] --> V1["validatePathFilter()Blocks .. and abs paths"]
    Input --> V2["validateRef()Strict char whitelist"]
    V1 --> Safe["Sanitized Args(string array)"]
    V2 --> Safe
    Safe --> ExecFile["execFile()No shell involved"]
    ExecFile --> Git["Git CLIread-only commands only"]
    Git --> Repo[".gitNo writes ever"]

    subgraph "Environment Hardening"
        E1["GIT_TERMINAL_PROMPT=0"]
        E2["GIT_PAGER=''"]
        E3["LC_ALL=C"]
        E4["30s timeout"]
        E5["50MB buffer limit"]
    end

    ExecFile -.-> E1 & E2 & E3 & E4 & E5

| Concern | Mitigation | |---------|------------| | Shell injection | All git commands use execFile (array args, no shell interpolation) | | Path traversal | validatePathFilter() blocks .. and absolute paths | | Ref injection | validateRef() validates git refs against a strict character whitelist | | Write operations | Strictly read-only. No tool modifies the repository in any way | | Network access | No external network calls. All data is local | | Git safety | GIT_TERMINAL_PROMPT=0 prevents interactive prompts; GIT_PAGER='' disables pagers | | Timeouts | 30-second default timeout on all git commands | | Buffer limits | 50MB max buffer to prevent memory exhaustion | We take security seriously. This server is designed to be safe to run on any machine with access to git repositories. Here are the key mitigations for potential attack vectors:

| Concern | Mitigation | |-----

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: hoangsonww
• Source: hoangsonww/GitIntel-MCP-Server
• License: MIT
• Homepage: https://hoangsonww.github.io/GitIntel-MCP-Server/

Install and usage instructions live in the source repository linked above.