{"id":"7d28f4d9-1db5-4ecc-a98d-fcf0f544f53c","slug":"gitintel-mcp-server","kind":"mcp","name":"GitIntel-MCP-Server","summary":"A Git intelligence MCP server built with Node.js and TypeScript that analyzes local Git repositories to surface insights like hotspots, churn, temporal coupling, knowledge maps, and risk scoring. Desi","owner":"hoangsonww","repoUrl":"https://github.com/hoangsonww/GitIntel-MCP-Server","license":"MIT","licenseTier":"permissive","trust":"community","stars":12,"match":null,"fewStars":false,"format":"mcp","createdAt":"2026-03-05T03:16:48.000Z","addedAt":"2026-10-14T05:07:01.081Z","logoUrl":"https://avatars.githubusercontent.com/u/124531104?u=db1cfb932b0d1749a1acc455ed77ca33a5c9b761&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["developer-tools","cloud-infra","memory-knowledge"],"tags":["claude-code","codex","esm","git","git-analysis","github","mcp-sdk","model-context-protocol-servers"],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-28T08:04:26.120Z","sample":false,"url":"https://conduits.dev/tools/gitintel-mcp-server","language":"TypeScript","transports":["stdio"],"install":{"npm":"mcp-git-intel"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# GitIntel - A Git Intelligence MCP Server for AI Agents\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n**Git Intelligence MCP Server** - deep repository analytics computed locally from your commit history.\n\nSurfaces 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.\n\nThis 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.).\n\n```\nYou: \"Analyze this repo -- show me hotspots, risk, and who knows the auth module best.\"\nClaude: [calls hotspots, risk_assessment, knowledge_map in parallel, returns formatted analysis]\n```\n\n---\n\n## Architecture\n\nGitIntel 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.\n\n```mermaid\ngraph LR\n A[MCP Client
Claude Code / Codex] <-->|stdio
JSON-RPC| B[mcp-git-intel
MCP Server]\n B -->|execFile| C[Git CLI]\n C --> D[Repository
.git]\n B --> E[Analysis Engine
scoring, formatting]\n```\n\nAll 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**.\n\n---\n\n## Tools\n\n12 analysis tools, each returning formatted tables, score bars, and actionable recommendations -- not raw git output.\n\n```mermaid\ngraph TD\n subgraph \"Change Analysis\"\n H[hotspots
Change frequency]\n CH[churn
Write/rewrite ratio]\n CT[complexity_trend
Complexity over time]\n end\n subgraph \"Dependency Analysis\"\n CO[coupling
Temporal coupling]\n end\n subgraph \"Team Analysis\"\n KM[knowledge_map
Who knows what]\n CS[contributor_stats
Team dynamics]\n CP[commit_patterns
Work patterns]\n end\n subgraph \"Risk & Release\"\n RA[risk_assessment
Change risk scoring]\n RN[release_notes
Changelog generation]\n BR[branch_risk
Branch health]\n end\n subgraph \"Code Archaeology\"\n FH[file_history
File evolution]\n CA[code_age
Staleness map]\n end\n```\n\n| Tool | What it does | Key insight |\n|------|-------------|-------------|\n| `hotspots` | Files that change most frequently | Top 4% of files by change frequency contain 50%+ of bugs |\n| `churn` | Code written then rewritten (additions vs deletions) | Churn ratio near 1.0 = code rewritten as fast as it's written |\n| `coupling` | Files that always change together | Hidden dependencies not visible in imports |\n| `knowledge_map` | Who knows a file/directory best, weighted by recency | Find the right reviewer, spot knowledge silos |\n| `complexity_trend` | How a file's complexity evolves over time | Catch files growing out of control |\n| `risk_assessment` | Risk score (0-100) for uncommitted or committed changes | Combines hotspot history, size, sensitivity, spread |\n| `release_notes` | Structured changelog from conventional commits | Groups by type, extracts breaking changes and PR refs |\n| `contributor_stats` | Team dynamics, collaboration graph, knowledge silos | Workload distribution, onboarding planning |\n| `file_history` | Full commit history of a single file with rename tracking | Trace why a file looks the way it does |\n| `code_age` | Age map showing when each file was last modified | Find dead code, abandoned features, stable infrastructure |\n| `commit_patterns` | Day-of-week, hour-of-day, commit size distributions | Spot weekend work, late-night hotfixes, oversized commits |\n| `branch_risk` | Branch staleness, divergence, and merge risk analysis | Branch hygiene, cleanup candidates, merge planning |\n\n## Data Pipeline\n\nEach tool transforms raw git output through a multi-stage pipeline:\n\n```mermaid\ngraph LR\n A[\"Git CLI
raw output\"] -->|parse| B[\"Structured Data
LogEntry[], stats\"]\n B -->|score| C[\"Scored Results
normalized 0-100\"]\n C -->|format| D[\"Formatted Output
tables, bars, text\"]\n D -->|wrap| E[\"MCP Response
CallToolResult\"]\n```\n\n## Resources\n\nResources are pre-computed summaries or feeds that can be read directly without arguments. Useful for quick snapshots or embedding into prompts.\n\n| Resource URI | Description |\n|-------------|-------------|\n| `git://repo/summary` | Repository snapshot: branch, last commit, total commits, active contributors, top languages, age, remote |\n| `git://repo/activity` | Recent 50-commit activity feed with stats |\n\n---\n\n## Installation\n\nThis server is **not published to npm**. You must clone, build, and register it locally.\n\n### Prerequisites\n\n- **Node.js** >= 18\n- **Git** >= 2.20\n\n### Build from source\n\n```bash\ngit clone https://github.com/hoangsonww/GitIntel-MCP-Server.git\ncd GitIntel-MCP-Server\nnpm install\nnpm run build\n```\n\n### Register with Claude Code\n\n> [!IMPORTANT]\n> **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.\n\n**Quick registration (analyzes cwd by default):**\n\n```bash\nclaude mcp add git-intel -- node /absolute/path/to/mcp-server/dist/index.js\n```\n\n**With a specific repository:**\n\n```bash\nclaude mcp add git-intel -- node /absolute/path/to/mcp-server/dist/index.js /path/to/your/repo\n```\n\n### Register with any MCP client (manual JSON)\n\nAdd to your MCP client's configuration file (e.g. `~/.claude.json` for Claude Code global config):\n\n```json\n{\n \"mcpServers\": {\n \"git-intel\": {\n \"type\": \"stdio\",\n \"command\": \"node\",\n \"args\": [\"/absolute/path/to/mcp-server/dist/index.js\"],\n \"env\": {}\n }\n }\n}\n```\n\n**With a pinned default repository** (optional — useful if you always analyze the same repo):\n\n```json\n{\n \"mcpServers\": {\n \"git-intel\": {\n \"type\": \"stdio\",\n \"command\": \"node\",\n \"args\": [\"/absolute/path/to/mcp-server/dist/index.js\"],\n \"env\": {\n \"GIT_INTEL_REPO\": \"/path/to/your/repo\"\n }\n }\n }\n}\n```\n\n> [!TIP]\n> **Tip**: The `~` home directory expansion works in the repo path argument (e.g. `~/projects/my-repo`).\n>\n> **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.\n\n---\n\n## Configuration\n\n### Default Repository Resolution\n\nThe server determines which git repository to use as the **default** using this priority order:\n\n| Priority | Method | Example |\n|----------|--------|---------|\n| 1 | CLI argument | `node dist/index.js /path/to/repo` |\n| 2 | Environment variable | `GIT_INTEL_REPO=/path/to/repo` |\n| 3 | Current working directory | Falls back to `process.cwd()` |\n\nThe `~` prefix is expanded to the user's home directory in all path inputs.\n\n### Per-Tool `repo_path` Override\n\nEvery 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:\n\n```json\n{ \"repo_path\": \"C:/Users/you/other-project\", \"days\": 90 }\n```\n\n### Resilient Startup (No-Crash Mode)\n\nThe server **never crashes** on startup, even when launched from a non-git directory. Instead:\n\n1. If a git repository is found, it becomes the default for all tools.\n2. 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.\n3. 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`.\n\n```mermaid\nflowchart TD\n Start[\"Server starts\"] --> CheckRepo{\"Is cwd a\\ngit repo?\"}\n CheckRepo -->|Yes| Default[\"Set as default repo\\nAll tools work immediately\"]\n CheckRepo -->|No| NoDefault[\"Start with no default\\nTools require repo_path\"]\n Default --> Ready[\"Server ready\\n12 tools, 2 resources\"]\n NoDefault --> Ready\n Ready --> Call{\"Tool called\"}\n Call --> HasArg{\"repo_path\\nprovided?\"}\n HasArg -->|Yes| UseArg[\"Use repo_path\"]\n HasArg -->|No| HasDefault{\"Default repo\\navailable?\"}\n HasDefault -->|Yes| UseDefault[\"Use default repo\"]\n HasDefault -->|No| Error[\"Return helpful error:\\n'Open Claude Code in a git repo\\nor pass repo_path'\"]\n UseArg --> Execute[\"Execute git analysis\"]\n UseDefault --> Execute\n```\n\nThis design means the server works as a **global MCP server** in Claude Code — it connects successfully regardless of which project directory you open.\n\n---\n\n## Usage Examples\n\nOnce 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.\n\n**Find bug-prone files:**\n> \"Show me the change hotspots in the last 60 days\"\n\n**Analyze code stability:**\n> \"What's the churn analysis for the src/api directory over the last quarter?\"\n\n**Find hidden dependencies:**\n> \"Which files are temporally coupled with src/auth/login.ts?\"\n\n**Find the right reviewer:**\n> \"Who knows the src/api directory best?\"\n\n**Track complexity growth:**\n> \"Show me the complexity trend for src/services/payment.ts\"\n\n**Assess change risk before merging:**\n> \"What's the risk assessment for the uncommitted changes?\"\n> \"Assess the risk of changes between main and feature-branch\"\n\n**Generate release notes:**\n> \"Generate release notes from v1.0.0 to HEAD\"\n\n**Understand team dynamics:**\n> \"Show me contributor statistics for the last 6 months\"\n> \"Who are the top collaborators and where are the knowledge silos?\"\n\n**Trace a file's evolution:**\n> \"Show me the full history of src/auth/login.ts\"\n\n**Find stale or abandoned code:**\n> \"What are the oldest files in the src/ directory?\"\n> \"Show me code age analysis for the project\"\n\n**Analyze work patterns:**\n> \"What are the commit patterns for the last 3 months?\"\n> \"When does the team usually commit?\"\n\n**Branch hygiene:**\n> \"Which branches are stale or highly diverged?\"\n> \"Show me branch risk analysis against main\"\n\n**Full repo analysis:**\n> \"Using git-intel, give me a comprehensive analysis of this repository\"\n\nSee [`docs/EXAMPLES.md`](docs/EXAMPLES.md) for a complete real-world transcript of a full repo analysis session.\n\n---\n\n## Development\n\n```mermaid\ngraph LR\n subgraph \"Development\"\n Dev[\"npm run dev
tsx auto-reload\"]\n CLI[\"npm run cli
Interactive REPL\"]\n end\n subgraph \"Testing\"\n Unit[\"npm test
Vitest unit tests\"]\n Smoke[\"npm run smoke
Full integration\"]\n end\n subgraph \"Quality\"\n Lint[\"npm run lint
tsc --noEmit\"]\n Fmt[\"npm run format
Prettier\"]\n end\n subgraph \"Ship\"\n Build[\"npm run build
TypeScript → dist/\"]\n end\n\n Dev --> Unit --> Lint --> Build\n CLI --> Smoke\n```\n\n```bash\nnpm run dev # Run server with tsx (auto-reload, uses cwd as repo)\nnpm run cli # Interactive REPL for testing tools and resources\nnpm run smoke # Automated smoke test -- runs every tool and resource\nnpm test # Run unit tests (vitest)\nnpm run test:watch # Watch mode\nnpm run lint # Type check (tsc --noEmit)\nnpm run build # Compile TypeScript to dist/\n```\n\n### CLI REPL\n\nThe 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.\n\n```mermaid\nsequenceDiagram\n participant User as Developer\n participant CLI as cli.ts (MCP Client)\n participant Server as index.ts (MCP Server)\n participant Git as Git CLI\n\n User->>CLI: npm run cli [repo_path]\n CLI->>Server: Spawn via StdioClientTransport\n Server-->>CLI: Connected (JSON-RPC over stdio)\n CLI->>User: git-intel> prompt\n\n User->>CLI: call hotspots {\"days\": 60}\n CLI->>Server: callTool(\"hotspots\", {days: 60})\n Server->>Git: git log --since=...\n Git-->>Server: raw output\n Server-->>CLI: formatted analysis\n CLI->>User: Display result + elapsed time\n\n User->>CLI: read git://repo/summary\n CLI->>Server: readResource(\"git://repo/summary\")\n Server-->>CLI: repo snapshot\n CLI->>User: Display result\n\n User->>CLI: exit\n CLI->>Server: close()\n```\n\n**Start the CLI:**\n\n```bash\nnpm run cli # Uses current directory as repo\nnpm run cli ~/projects/myapp # Analyze a specific repo\n```\n\n**Available commands:**\n\n| Command | Description |\n|---------|-------------|\n| `tools` | List all registered tools with parameters |\n| `resources` | List all registered resources |\n| `call [json]` | Call a tool with optional JSON arguments |\n| `read ` | Read a resource by URI |\n| `help` | Show help |\n| `exit` / `quit` / `q` | Quit the CLI |\n\n**Example session:**\n\n```\ngit-intel> tools\n Available tools (12):\n hotspots Identify files that change most frequently...\n params: repo_path, days, limit, path_filter\n churn Analyze code churn...\n params: repo_path, days, limit, path_filter\n ...\n\ngit-intel> call hotspots {\"days\": 60, \"limit\": 5}\n Calling hotspots...\n (42ms)\n\n## Change Hotspots (last 60 days)\nFile Changes Authors Last Changed Heat\n-------------------- ------- ------- ------------ ---------------\nsrc/index.ts 12 2 2026-03-08 [██████████] 100\nsrc/tools/risk.ts 8 1 2026-03-07 [██████░░░░] 67\n...\n\ngit-intel> call knowledge_map {\"path\": \"src/auth\"}\n Calling knowledge_map...\n (38ms)\n\n## Knowledge Map: src/auth (last 365 days)\n...\n\ngit-intel> call risk_assessment\n Calling risk_assessment...\n (125ms)\n\n## Risk Assessment: uncommitted changes\n...\n\ngit-intel> read git://repo/summary\n Reading git://repo/summary...\n (15ms)\n\nBranch: master\nLast commit: c4934239 by dav nguyxn on 2026-03-09\n...\n\ngit-intel> exit\nBye.\n```\n\nSee [`docs/CLI.md`](docs/CLI.md) for the full CLI reference.\n\n> [!TIP]\n> This is useful for manual testing and debugging without needing to go through an AI client.\n\n### Smoke Test\n\n`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.\n\n---\n\n## Security Model\n\n```mermaid\ngraph LR\n Input[\"User / AI Input\"] --> V1[\"validatePathFilter()
Blocks .. and abs paths\"]\n Input --> V2[\"validateRef()
Strict char whitelist\"]\n V1 --> Safe[\"Sanitized Args
(string array)\"]\n V2 --> Safe\n Safe --> ExecFile[\"execFile()
No shell involved\"]\n ExecFile --> Git[\"Git CLI
read-only commands only\"]\n Git --> Repo[\".git
No writes ever\"]\n\n subgraph \"Environment Hardening\"\n E1[\"GIT_TERMINAL_PROMPT=0\"]\n E2[\"GIT_PAGER=''\"]\n E3[\"LC_ALL=C\"]\n E4[\"30s timeout\"]\n E5[\"50MB buffer limit\"]\n end\n\n ExecFile -.-> E1 & E2 & E3 & E4 & E5\n```\n\n| Concern | Mitigation |\n|---------|------------|\n| Shell injection | All git commands use `execFile` (array args, no shell interpolation) |\n| Path traversal | `validatePathFilter()` blocks `..` and absolute paths |\n| Ref injection | `validateRef()` validates git refs against a strict character whitelist |\n| Write operations | Strictly read-only. No tool modifies the repository in any way |\n| Network access | No external network calls. All data is local |\n| Git safety | `GIT_TERMINAL_PROMPT=0` prevents interactive prompts; `GIT_PAGER=''` disables pagers |\n| Timeouts | 30-second default timeout on all git commands |\n| Buffer limits | 50MB max buffer to prevent memory exhaustion |\nWe 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:\n\n| Concern | Mitigation |\n|------------------|--------------------------------------------------------------------------------------|\n| Shell injection | All git commands use `execFile` (array args, no shell interpolation) |\n| Path traversal | `validatePathFilter()` blocks `..` and absolute paths |\n| Ref injection | `validateRef()` validates git refs against a strict character whitelist |\n| Write operations | Strictly read-only. No tool modifies the repository in any way |\n| Network access | No external network calls. All data is local |\n| Git safety | `GIT_TERMINAL_PROMPT=0` prevents interactive prompts; `GIT_PAGER=''` disables pagers |\n| Timeouts | 30-second default timeout on all git commands |\n| Buffer limits | 50MB max buffer to prevent memory exhaustion |\n\n---\n\n## Project Structure\n\nThe code is organized into clear modules for git interaction, analysis tools, resources, and utilities. The entry point (`index.ts`) sets up the MCP server and registers all tools and resources.\n\n```\nsrc/\n index.ts Entry point, server setup, tool/resource registration (resilient startup)\n cli.ts Interactive REPL for testing\n smoke-test.ts Automated smoke test\n git/\n executor.ts Safe git command runner (execFile, timeouts, env)\n parser.ts Git output parsers (log, numstat, conventional commits)\n repo.ts Repo validation, path/ref sanitization\n tools/\n hotspots.ts Change frequency analysis\n churn.ts Code churn (additions vs deletions)\n coupling.ts Temporal coupling detection\n knowledge-map.ts Knowledge scoring per author\n complexity.ts Complexity trend over time\n risk.ts Multi-factor risk assessment\n release-notes.ts Changelog from conventional commits\n contributors.ts Contributor analytics and collaboration\n file-history.ts Single-file evolution with rename tracking\n code-age.ts File staleness and age distribution\n commit-patterns.ts Work pattern analytics (time, size)\n branch-risk.ts Branch staleness and divergence detection\n resources/\n summary.ts Repository snapshot resource (graceful degradation)\n activity.ts Recent commit activity feed (graceful degradation)\n util/\n scoring.ts Normalization, recency decay, coupling, risk scoring\n formatting.ts Tables, score bars, text output helpers\n resolve-repo.ts Per-call repo resolution with fallback chain and error messages\n```\n\n---\n\n## Further Documentation\n\nThis README provides a high-level overview. For deeper technical details, see:\n\n- **[`ARCHITECTURE.md`](ARCHITECTURE.md)** -- Deep technical architecture, design decisions, module dependencies\n- **[`docs/TOOLS.md`](docs/TOOLS.md)** -- Detailed reference for every tool (schemas, examples, interpretation)\n- **[`docs/CLI.md`](docs/CLI.md)** -- Full CLI reference with all commands, parameters, and examples\n- **[`docs/EXAMPLES.md`](docs/EXAMPLES.md)** -- Real-world usage transcript showing a full repo analysis session\n\n## License\n\nMIT. See [LICENSE](LICENSE) for details.\n\n## Author\n\nCreated by [Son Nguyen](https://sonnguyenhoang.com) in 2026. Contributions are welcome! See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for guidelines.\n"}