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 contributors
get_repository_stats - Detailed repository statistics
get_author_stats - Complete contributor analysis
get_branch_stats - Branch health and comparison metrics
get_file_stats - File modification patterns and hotspots
get_commit_history - Detailed commit timeline with filters
get_commit_frequency - Daily commit patterns over time
get_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": "[email protected]",
    "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.

Git Analytics