Git Analytics MCP Server
🚀 A comprehensive Model Context Protocol (MCP) server that provides detailed Git repository analytics and insights. Perfect for developers who want to understand their codebase better through data-driven insights.
📊 Features
Repository Analytics
- Comprehensive Stats: Total commits, authors, branches, and code changes
- Author Analysis: Contributor rankings, commit patterns, and activity periods
- Branch Intelligence: Branch health, ahead/behind status, and activity metrics
- File Insights: Most modified files, author contributions per file
- Temporal Analysis: Commit frequency, code churn over time
- Visual Reports: Beautifully formatted terminal output with colors and emojis
Available Tools
get_repository_overview- Executive summary with key metrics and top contributorsget_repository_stats- Detailed repository statisticsget_author_stats- Complete contributor analysisget_branch_stats- Branch health and comparison metricsget_file_stats- File modification patterns and hotspotsget_commit_history- Detailed commit timeline with filtersget_commit_frequency- Daily commit patterns over timeget_code_churn- Lines added/removed analysis
🛠 Installation
Prerequisites
- Node.js 18+
- npm or yarn
- Git repository to analyze
Quick Setup
# Clone or create the project
cd ~/git-analytics-mcp-server
# Install dependencies
npm install
# Build the project
npm run build
# Test the server (optional)
npm test
Development Mode
# Run in development with auto-reload
npm run dev
🚀 Usage
As MCP Server
Add to your MCP client configuration:
{
"mcpServers": {
"git-analytics": {
"command": "node",
"args": ["/path/to/git-analytics-mcp-server/dist/index.js"]
}
}
}
Direct CLI Usage
# Install globally
npm install -g .
# Use anywhere
git-analytics-mcp
📈 Example Analytics
Repository Overview
📊 REPOSITORY SUMMARY REPORT
──────────────────────────────────────────────────
Repository Statistics:
• Total Commits: 1,247
• Total Authors: 12
• Active Branches: 8
• Code Changes: +45,678 -12,345
• Repository Age: 2023-01-15 to 2024-06-15
Top Contributors:
🥇 John Doe - 456 commits
🥈 Jane Smith - 234 commits
🥉 Bob Wilson - 189 commits
🏅 Alice Brown - 145 commits
🏅 Mike Johnson - 123 commits
Recent Activity:
• a1b2c3d4 Add new authentication module (John Doe)
• e5f6g7h8 Fix critical security vulnerability (Jane Smith)
• i9j0k1l2 Update documentation and examples (Bob Wilson)
Author Analysis
[
{
"name": "John Doe",
"email": "john@example.com",
"commits": 456,
"insertions": 12340,
"deletions": 3456,
"firstCommit": "2023-01-15T10:30:00Z",
"lastCommit": "2024-06-15T14:22:00Z"
}
]
Code Churn Analysis
[
{
"date": "2024-06-01",
"insertions": 234,
"deletions": 45,
"net": 189
},
{
"date": "2024-06-02",
"insertions": 156,
"deletions": 89,
"net": 67
}
]
🔧 Configuration
Tool Parameters
Most tools accept these common parameters:
path(string): Repository path (default: current directory)days(number): Time range for analysis (default: 30)limit(number): Maximum results to return (default: 50)
Environment Variables
# Set default repository path
export GIT_ANALYTICS_DEFAULT_PATH="/path/to/repo"
# Enable debug logging
export GIT_ANALYTICS_DEBUG=true
🧪 Testing
# Run all tests
npm test
# Run with coverage
npm run test:coverage
# Test specific functionality
npm run test -- --grep "author stats"
Test Repository Setup
# Create test repository
mkdir test-repo && cd test-repo
git init
echo "# Test" > README.md
git add . && git commit -m "Initial commit"
# Test the server
node dist/index.js
📊 Use Cases
Development Team Analytics
- Code Review Insights: Identify files that need more attention
- Team Productivity: Track commit patterns and contribution metrics
- Technical Debt: Find files with high churn rates
- Onboarding: Understand codebase structure and key contributors
Project Management
- Release Planning: Analyze recent development velocity
- Resource Allocation: Identify knowledge silos and areas needing support
- Quality Metrics: Track code stability through churn analysis
- Timeline Analysis: Understand development patterns and cycles
Repository Health
- Branch Management: Identify stale or problematic branches
- File Hotspots: Find files that may need refactoring
- Contributor Onboarding: Welcome new team members with context
- Historical Analysis: Learn from past development patterns
🛠 Advanced Features
Custom Analytics
Extend the server with custom analytics:
// Add to git-analytics.ts
async getCustomMetric(): Promise<CustomMetric> {
// Your custom analysis logic
}
Integration Examples
# Use with GitHub CLI
gh repo list | xargs -I {} git-analytics-mcp --path {}
# Batch analysis
find ~/projects -name ".git" -type d | \
xargs -I {} dirname {} | \
xargs -I {} git-analytics-mcp --path {}
🐛 Troubleshooting
Common Issues
"Invalid Git repository"
- Ensure you're in a Git repository or provide correct path
- Check Git installation:
git --version
"Permission denied"
- Verify read access to repository
- Check file permissions on .git directory
"No commits found"
- Repository may be empty or newly initialized
- Try with a repository that has commits
Debug Mode
# Enable verbose logging
DEBUG=git-analytics:* npm start
# Check server connectivity
echo '{}' | node dist/index.js
🤝 Contributing
- Fork the repository
- Create feature branch:
git checkout -b feature/amazing-feature - Commit changes:
git commit -m 'Add amazing feature' - Push to branch:
git push origin feature/amazing-feature - Open Pull Request
Development Setup
# Install dev dependencies
npm install
# Run in watch mode
npm run dev
# Lint code
npm run lint
# Format code
npm run format
📄 License
MIT License - see LICENSE file for details.
🌟 Acknowledgments
- Model Context Protocol for the excellent framework
- simple-git for Git operations
- chalk for beautiful terminal output
- date-fns for date manipulation
Happy Analyzing! 📊✨
For questions, issues, or feature requests, please open an issue on GitHub.