@iflow-mcp/hoangsonww-gitintel-mcp-server
v1.0.0
Published
Git Intelligence MCP Server — deep repository analytics from commit history
Downloads
74
Readme
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
graph LR
A[MCP Client<br/>Claude Code / Codex] <-->|stdio<br/>JSON-RPC| B[mcp-git-intel<br/>MCP Server]
B -->|execFile| C[Git CLI]
C --> D[Repository<br/>.git]
B --> E[Analysis Engine<br/>scoring, 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[hotspots<br/>Change frequency]
CH[churn<br/>Write/rewrite ratio]
CT[complexity_trend<br/>Complexity over time]
end
subgraph "Dependency Analysis"
CO[coupling<br/>Temporal coupling]
end
subgraph "Team Analysis"
KM[knowledge_map<br/>Who knows what]
CS[contributor_stats<br/>Team dynamics]
CP[commit_patterns<br/>Work patterns]
end
subgraph "Risk & Release"
RA[risk_assessment<br/>Change risk scoring]
RN[release_notes<br/>Changelog generation]
BR[branch_risk<br/>Branch health]
end
subgraph "Code Archaeology"
FH[file_history<br/>File evolution]
CA[code_age<br/>Staleness 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 CLI<br/>raw output"] -->|parse| B["Structured Data<br/>LogEntry[], stats"]
B -->|score| C["Scored Results<br/>normalized 0-100"]
C -->|format| D["Formatted Output<br/>tables, bars, text"]
D -->|wrap| E["MCP Response<br/>CallToolResult"]Resources
| 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 buildRegister 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_pathto every tool call manually.
Quick registration (analyzes cwd by default):
claude mcp add git-intel -- node /absolute/path/to/mcp-server/dist/index.jsWith a specific repository:
claude mcp add git-intel -- node /absolute/path/to/mcp-server/dist/index.js /path/to/your/repoRegister 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: The
~home directory expansion works in the repo path argument (e.g.~/projects/my-repo).Tip: When registered globally (in
~/.claude.json), the server auto-detects the git repo in your current working directory. NoGIT_INTEL_REPOneeded — 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:
- If a git repository is found, it becomes the default for all tools.
- If no git repository is found, the server starts anyway with no default repo. Tools require the
repo_pathparameter to specify which repo to analyze. - Resources (
git://repo/summary,git://repo/activity) return informative messages directing the user to open Claude Code inside a git repo or userepo_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 --> ExecuteThis 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 for a complete real-world transcript of a full repo analysis session.
Development
graph LR
subgraph "Development"
Dev["npm run dev<br/>tsx auto-reload"]
CLI["npm run cli<br/>Interactive REPL"]
end
subgraph "Testing"
Unit["npm test<br/>Vitest unit tests"]
Smoke["npm run smoke<br/>Full integration"]
end
subgraph "Quality"
Lint["npm run lint<br/>tsc --noEmit"]
Fmt["npm run format<br/>Prettier"]
end
subgraph "Ship"
Build["npm run build<br/>TypeScript → dist/"]
end
Dev --> Unit --> Lint --> Build
CLI --> Smokenpm 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 repoAvailable commands:
| Command | Description |
|---------|-------------|
| tools | List all registered tools with parameters |
| resources | List all registered resources |
| call <tool> [json] | Call a tool with optional JSON arguments |
| read <uri> | 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 for the full CLI reference.
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()<br/>Blocks .. and abs paths"]
Input --> V2["validateRef()<br/>Strict char whitelist"]
V1 --> Safe["Sanitized Args<br/>(string array)"]
V2 --> Safe
Safe --> ExecFile["execFile()<br/>No shell involved"]
ExecFile --> Git["Git CLI<br/>read-only commands only"]
Git --> Repo[".git<br/>No 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 |
Project Structure
src/
index.ts Entry point, server setup, tool/resource registration (resilient startup)
cli.ts Interactive REPL for testing
smoke-test.ts Automated smoke test
git/
executor.ts Safe git command runner (execFile, timeouts, env)
parser.ts Git output parsers (log, numstat, conventional commits)
repo.ts Repo validation, path/ref sanitization
tools/
hotspots.ts Change frequency analysis
churn.ts Code churn (additions vs deletions)
coupling.ts Temporal coupling detection
knowledge-map.ts Knowledge scoring per author
complexity.ts Complexity trend over time
risk.ts Multi-factor risk assessment
release-notes.ts Changelog from conventional commits
contributors.ts Contributor analytics and collaboration
file-history.ts Single-file evolution with rename tracking
code-age.ts File staleness and age distribution
commit-patterns.ts Work pattern analytics (time, size)
branch-risk.ts Branch staleness and divergence detection
resources/
summary.ts Repository snapshot resource (graceful degradation)
activity.ts Recent commit activity feed (graceful degradation)
util/
scoring.ts Normalization, recency decay, coupling, risk scoring
formatting.ts Tables, score bars, text output helpers
resolve-repo.ts Per-call repo resolution with fallback chain and error messagesFurther Documentation
ARCHITECTURE.md-- Deep technical architecture, design decisions, module dependenciesdocs/TOOLS.md-- Detailed reference for every tool (schemas, examples, interpretation)docs/CLI.md-- Full CLI reference with all commands, parameters, and examplesdocs/EXAMPLES.md-- Real-world usage transcript showing a full repo analysis session
License
MIT. See LICENSE for details.