Git Metrics MCP Server
MCP server for analyzing git repository metrics and understanding team health. Built for Kiro CLI (Amazon Q CLI) and other MCP clients.
Overview
This server provides tools to extract meaningful metrics from git repositories, helping teams understand their development patterns, identify risks early, and have better conversations about code quality and team health.
This is a mirror, not a microscope. Use it to reflect on team health and process quality, not to surveil individual behavior.
Features
- Commit Statistics: Track commits, additions, deletions, and files changed
- Author Metrics: Per-developer performance breakdown
- File Churn Analysis: Identify frequently modified files (quality indicators)
- Team Summaries: Comprehensive team performance reports
- Commit Patterns: Analyze when people commit (burnout detection)
- Code Ownership: Bus factor and knowledge distribution analysis
- Velocity Trends: Week/month productivity tracking
- Collaboration Metrics: Team interaction patterns
- Quality Metrics: Commit size, reverts, and fix rates
- Technical Debt: Stale files and complexity hotspots
- Conventional Commits: Analyze commit types, scopes, and release frequency
Production Features
- Input Sanitization: Protection against command injection attacks
- Structured Logging: JSON-formatted logs with timestamps for monitoring
- Configurable Timeouts: Set
GIT_TIMEOUTenv var (default: 30s) - Error Boundaries: Graceful error handling with detailed logging
- CI/CD: Automated testing on pull requests via GitHub Actions
Installation
From npm (Recommended)
npm install -g @jonmatum/git-metrics-mcp-server
From Source
git clone https://github.com/jonmatum/git-metrics-mcp-server.git
cd git-metrics-mcp-server
npm install
npm run build
Kiro CLI Configuration
Add to ~/.kiro/settings/mcp.json:
If installed globally:
{
"mcpServers": {
"git-metrics": {
"command": "git-metrics-mcp-server",
"args": []
}
}
}
If using npx:
{
"mcpServers": {
"git-metrics": {
"command": "npx",
"args": ["@jonmatum/git-metrics-mcp-server"]
}
}
}
If running from source:
{
"mcpServers": {
"git-metrics": {
"command": "npx",
"args": ["tsx", "/path/to/git-metrics-mcp-server/src/git-metrics.ts"]
}
}
}
Usage with Kiro CLI
Start Kiro CLI:
kiro-cli chat
Then ask natural language questions:
Get commit stats for /home/user/myproject since 2025-11-01
Show me team summary and velocity trends for the last 2 weeks
What's our bus factor? Who are single points of failure?
Show me commit patterns - are people committing late at night?
What files have the most churn since October?
Identify technical debt and complexity hotspots
For comprehensive analysis, see the Analysis Prompt.
Available Tools
Note on Date Ranges: The
untilparameter is inclusive - commits on the end date are included in results. For example,since="2025-11-01" until="2025-11-30"includes all commits from November 1st through November 30th.
get_commit_stats
Get overall commit statistics for a time period.
Parameters:
repo_path(required): Path to git repositorysince(required): Start date (YYYY-MM-DD)until(optional): End date (YYYY-MM-DD), inclusiveauthor(optional): Filter by author
Returns:
{
"commits": 45,
"additions": 1250,
"deletions": 380,
"filesChanged": 67,
"netChange": 870
}
get_author_metrics
Detailed metrics per contributor.
Parameters:
repo_path(required): Path to git repositorysince(required): Start date (YYYY-MM-DD)until(optional): End date (YYYY-MM-DD)
Returns:
{
"John Doe <john@example.com>": {
"commits": 23,
"additions": 650,
"deletions": 120,
"files": 34
}
}
get_file_churn
Files with most changes (indicates complexity or issues).
Parameters:
repo_path(required): Path to git repositorysince(required): Start date (YYYY-MM-DD)until(optional): End date (YYYY-MM-DD), inclusivelimit(optional): Number of files, default 10
Returns:
[
{ "file": "src/main.ts", "changes": 15 },
{ "file": "src/utils.ts", "changes": 12 }
]
get_team_summary
Comprehensive team performance report.
Parameters:
repo_path(required): Path to git repositorysince(required): Start date (YYYY-MM-DD)until(optional): End date (YYYY-MM-DD)
Returns:
{
"period": { "since": "2025-11-01", "until": "now" },
"team": {
"totalCommits": 45,
"totalAdditions": 1250,
"totalDeletions": 380,
"contributors": 3
},
"contributors": { ... }
}
get_commit_patterns
Analyze when people commit (burnout detection).
Parameters:
repo_path(required): Path to git repositorysince(required): Start date (YYYY-MM-DD)until(optional): End date (YYYY-MM-DD)
Returns:
{
"byDay": { "Mon": 45, "Tue": 38, ... },
"byHour": { "09": 12, "14": 18, ... },
"patterns": {
"weekendPercentage": "15.2%",
"lateNightPercentage": "8.3%"
}
}
Note: Hours are shown in the author's local timezone at the time of commit.
get_code_ownership
Bus factor and knowledge distribution.
Parameters:
repo_path(required): Path to git repositorysince(required): Start date (YYYY-MM-DD)until(optional): End date (YYYY-MM-DD), inclusive
Returns:
{
"totalFiles": 150,
"sharedFiles": 80,
"soloFiles": 70,
"busFactor": [
{ "author": "John <john@example.com>", "exclusiveFiles": 25 }
]
}
get_velocity_trends
Track velocity over time.
Parameters:
repo_path(required): Path to git repositorysince(required): Start date (YYYY-MM-DD)until(optional): End date (YYYY-MM-DD), inclusiveinterval(optional): "week" or "month", default "week"
Returns:
{
"interval": "week",
"trends": [
{ "period": "2025-11-01", "commits": 45, "additions": 1250, "deletions": 380 }
]
}
get_collaboration_metrics
Team interaction patterns.
Parameters:
repo_path(required): Path to git repositorysince(required): Start date (YYYY-MM-DD)until(optional): End date (YYYY-MM-DD), inclusive
Returns:
{
"collaborativeFiles": 80,
"topCollaborations": [
{ "pair": "John <-> Jane", "sharedFiles": 25 }
]
}
get_quality_metrics
Code quality indicators.
Parameters:
repo_path(required): Path to git repositorysince(required): Start date (YYYY-MM-DD)until(optional): End date (YYYY-MM-DD), inclusive
Returns:
{
"averageCommitSize": 125,
"medianCommitSize": 85,
"revertRate": "2.3%",
"fixRate": "18.5%"
}
get_technical_debt
Identify technical debt.
Parameters:
repo_path(required): Path to git repositorystale_days(optional): Days to consider stale, default 90
Returns:
{
"staleFiles": [
{ "file": "old-module.js", "daysSinceLastChange": 180 }
],
"complexityHotspots": [
{ "file": "big-file.js", "churn": 25 }
]
}
get_conventional_commits
Analyze conventional commit usage and release patterns.
Parameters:
repo_path(required): Path to git repositorysince(required): Start date (YYYY-MM-DD)until(optional): End date (YYYY-MM-DD), inclusive
Returns:
{
"totalCommits": 25,
"conventionalCommits": 25,
"conventionalPercentage": "100.0%",
"commitTypes": [
{ "type": "feat", "count": 5 },
{ "type": "fix", "count": 5 }
],
"topScopes": [
{ "scope": "main", "count": 8 }
],
"breakingChanges": 0,
"recentReleases": [
{ "tag": "v2.0.1", "date": "2025-11-24" }
],
"releaseFrequency": "8 releases since 2025-11-01"
}
Real-World Use Case: Team Health Analysis
Here's how a real engineering team used this tool to understand their development patterns across 5 repositories with 83 contributors:
The Challenge
A team needed to understand their development health across multiple repositories without manually parsing git logs. They wanted to identify risks, improve collaboration, and ensure sustainable work practices.
What They Discovered
Team Health Insights:
- ✅ Excellent work-life balance: Only 1.3% weekend commits
- ✅ Strong release discipline: 114 releases with 86.3% conventional commit adoption
- ⚠️ Bus factor risk: Two developers owned 61% of exclusive files in one repo
- ⚠️ High fix rate (36.3%) indicated reactive development in one project
Collaboration Patterns:
- Best practice: One repo had 88.9% shared files (excellent knowledge distribution)
- Needs improvement: Another repo had only 30.5% shared files
- Identified top collaboration pairs for knowledge sharing
Code Quality Indicators:
- Found complexity hotspots: Files with 66+ changes needing refactoring
- Identified technical debt: Stale files and high-churn areas
- Discovered optimal commit patterns: Median 17 lines (focused commits)
Actions Taken
- Immediate: Scheduled knowledge transfer sessions for high bus factor areas
- Process: Implemented pair programming to increase file sharing
- Quality: Added pre-commit hooks to reduce fix rate
- Culture: Replicated best practices from high-performing repos
Time Saved: What would have taken days of manual analysis was completed in minutes with natural language queries.
Read the full analysis: team-activity-analysis.md
Use Cases
✅ Good Use Cases
Sprint Retrospectives
Show me team summary and velocity trends for the last 2 weeks
What's our commit pattern? Are we burning out?
Risk Management
What's our bus factor? Who are single points of failure?
Show me code ownership - where do we have knowledge concentration?
Code Quality Reviews
Show me quality metrics and technical debt
What files have high churn and need refactoring?
Team Health Checks
Are people committing late at night or on weekends?
Show me collaboration metrics - is the team working together?
Onboarding Support
Get commit stats for new-dev@example.com since their start date
Show their velocity trend over the first 3 months
❌ What This Is NOT For
- ❌ Micromanagement or surveillance
- ❌ Comparing developers against each other
- ❌ Performance review ammunition
- ❌ Daily productivity tracking
Team Health Indicators You Can Track
Risk Management
- Bus Factor: Knowledge concentration risk - who are single points of failure?
- Code Ownership: File sharing patterns - is knowledge distributed?
- Technical Debt: Stale files, complexity hotspots needing attention
Team Well-being
- Burnout Indicators: Weekend/late-night commits - is the team overworked?
- Work Patterns: When people commit - are boundaries healthy?
- Velocity Trends: Sustainable pace or sprint-and-crash cycles?
Code Quality
- Churn: Files changed repeatedly (quality indicator)
- Commit Size: Focused commits vs. large dumps
- Revert Rate: How often do we undo work?
- Fix Rate: Reactive (high fixes) vs. proactive development
Collaboration Health
- File Sharing: How much code is touched by multiple people?
- Collaboration Pairs: Who works together most often?
- Contribution Balance: Even distribution or bottlenecks?
Process Maturity
- Conventional Commits: Adoption rate of commit standards
- Release Frequency: How often do we ship?
- Breaking Changes: How disruptive are our releases?
Tips for Responsible Usage
How to Use This Tool Well
- Use natural language: Kiro understands context, so ask questions naturally
- Focus on trends, not snapshots: Weekly/monthly patterns matter more than daily counts
- Combine metrics: Ask for multiple analyses to get the full picture
- Start conversations, don't end them: Use data to ask "why?" not to judge
- Look for patterns: Team health indicators, not individual performance scores
- Regular reviews: Weekly health checks (5 min), sprint retrospectives (15 min), monthly trends (30 min)
Red Flags (Don't Do This)
- ❌ Checking metrics more than once per day
- ❌ Creating leaderboards or rankings
- ❌ Setting commit quotas or targets
- ❌ Using metrics in performance reviews without context
- ❌ Comparing developers directly
Green Flags (Good Usage)
- ✅ You check trends weekly/monthly, not daily
- ✅ You ask "what does this tell us about our process?"
- ✅ You use it to start conversations, not end them
- ✅ You focus on team health, not individual performance
- ✅ You look for patterns, not outliers
- ✅ You use it to help, not judge
Remember: The best teams are built on trust, not metrics. Use this tool to support your team, not surveil them.
Development
npm run dev # Run in development mode
npm run build # Build for production
npm start # Run built version
Testing
npm test # Run tests
npm run test:watch # Run tests in watch mode
npm run test:coverage # Run tests with coverage report
The test suite covers:
- Date validation
- Repository path validation
- Git command execution
- Commit data parsing
- Core git operations (stats, metrics, churn, velocity)
License
MIT - See LICENSE file
Author
Jonatan Mata (@jonmatum)
Contributing
Issues and PRs welcome at https://github.com/jonmatum/git-metrics-mcp-server
Support
- GitHub Issues: https://github.com/jonmatum/git-metrics-mcp-server/issues
- MCP Documentation: https://modelcontextprotocol.io/