TL;DR - Git MCP Quick Start
Understand your local repository history with AI - View diffs, logs, and blame with natural language.
🆕 2025: Git MCP now part of Agentic AI Foundation. Protocol version 2025-11-25 with enhanced context support! For an introduction to MCP, see the MCP Introduction guide.
Quick Setup:
{
"mcpServers": {
"git": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-git",
"--repository",
"/path/to/your/repo"
]
}
}
}What you can do:
- 📊 Status: View current changes
- 📝 Diff: See what’s modified
- 📜 Log: Browse commit history
- 🔍 Blame: Find who changed what
- 🌿 Branches: View and compare branches
- 📦 Show: Examine any commit
Example conversation:
You: What changes have I made that aren't committed yet?
Claude: You have 3 modified files:
**src/auth.ts** (Modified)
- Added password validation function
- Updated login error messages
**tests/auth.test.ts** (Modified)
- Added 5 new test cases
**package.json** (Modified)
- Added bcrypt dependency💡 Works locally - No remote access needed. Perfect for understanding code before commits.
🤖 2025 Update: Works with Claude, ChatGPT, GitHub Copilot, and all MCP-compatible AI tools.
Git MCP vs GitHub MCP
A common question: when to use which?
| Aspect | Git MCP | GitHub MCP |
|---|---|---|
| Scope | Local repository | Remote GitHub |
| Operations | status, diff, log, blame | issues, PRs, repo mgmt |
| Authentication | None needed | Personal Access Token |
| Use Case | Understanding code changes | Managing projects |
When to Use Git MCP
- Reviewing local changes before commit
- Understanding code history and blame
- Exploring branch differences
- Learning a new codebase
For AI coding assistance, see the AI-Powered IDEs Comparison guide.
When to Use GitHub MCP
- Creating/managing issues and PRs
- Managing repository settings
- Cross-repository operations
- Remote collaboration
2025: Remote Git via GitMCP
New in 2025, GitMCP transforms any GitHub project into a remote MCP endpoint:
Remote URL: gitmcp.io/owner/repo
Benefits:
- No local clone needed
- Semantic search across docs
- AI understands full project contextUsing Both Together
{
"mcpServers": {
"git": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-git", "--repository", "."]
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx"
}
}
}
}Now you can:
- “Show what I’ve changed locally” (Git MCP)
- “Create a PR for these changes” (GitHub MCP)
Installation & Configuration
Prerequisites
- Git installed locally (check with
git --version) - Node.js v18+ (check with
node --version) - A Git repository to analyze
Claude Desktop Setup
Add to claude_desktop_config.json:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json
{
"mcpServers": {
"git": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-git",
"--repository",
"/Users/yourname/projects/my-app"
]
}
}
}Current Directory (for Cursor)
Use . to reference the current workspace:
{
"mcpServers": {
"git": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-git",
"--repository",
"."
]
}
}
}Multiple Repositories
Configure separate servers for different projects:
{
"mcpServers": {
"git-frontend": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-git",
"--repository", "/projects/frontend"]
},
"git-backend": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-git",
"--repository", "/projects/backend"]
},
"git-docs": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-git",
"--repository", "/projects/documentation"]
}
}
}Verify Installation
Restart your AI client and test:
You: What's the git status of my project?
Claude: Here's your repository status:
**Branch:** main (up to date with origin/main)
**Staged Changes:**
- (none)
**Modified Files:**
- src/utils.ts
- tests/utils.test.ts
**Untracked Files:**
- src/new-feature.ts
- docs/api-changes.mdAvailable Tools
The Git MCP server provides these read-only operations:
Status & Changes
| Tool | Description | Example Prompt |
|---|---|---|
git_status | Show working tree status | ”What files have I modified?” |
git_diff | Show changes in files | ”Show me the diff for utils.ts” |
git_diff_staged | Show staged changes | ”What will be in my next commit?” |
History & Log
| Tool | Description | Example Prompt |
|---|---|---|
git_log | View commit history | ”Show last 10 commits” |
git_show | Show a specific commit | ”What changed in abc123?” |
git_blame | Show who changed each line | ”Who wrote this function?” |
Branches
| Tool | Description | Example Prompt |
|---|---|---|
git_branch | List branches | ”What branches exist?” |
git_diff_branch | Compare branches | ”What’s different in feature/x?” |
Search
| Tool | Description | Example Prompt |
|---|---|---|
git_search | Search commits | ”Find commits mentioning ‘auth‘“ |
Practical Workflows
Workflow 1: Pre-Commit Review
Before committing, have AI review your changes. For more on AI-assisted development, see the CLI Tools for AI guide.
You: Review all my uncommitted changes and identify any issues
Claude: I'll analyze your changes...
**Modified Files (3):**
📄 **src/api/auth.ts**
Changes: +45 lines, -12 lines
Issues found:
- ⚠️ Line 67: console.log with password (remove before commit!)
- ℹ️ Line 89: Consider adding error handling for edge case
📄 **src/utils/validation.ts**
Changes: +23 lines, -0 lines
✅ Looks good - clean implementation
📄 **tests/auth.test.ts**
Changes: +78 lines, -5 lines
✅ Good test coverage for new features
**Recommendation:**
Remove the debug console.log on line 67 of auth.ts
before committing.Workflow 2: Understanding Code History
When you need to understand why code is the way it is:
You: Show me the history of changes to src/config.ts
and explain why it evolved this way
Claude: Analyzing commit history for src/config.ts...
**File History (Last 10 commits):**
1. **abc1234** - Dec 20 (Alice)
"Add rate limiting config"
- Added RATE_LIMIT_* constants
2. **def5678** - Dec 15 (Bob)
"Refactor env handling"
- Moved from process.env to config object
- Added validation on startup
3. **ghi9012** - Dec 10 (Alice)
"Add database connection pool config"
- Added DB_POOL_MIN, DB_POOL_MAX
4. **jkl3456** - Nov 28 (Carol)
"Initial config setup"
- Created file with basic settings
**Evolution Summary:**
The config started simple (Carol), then got proper
environment handling (Bob), database pooling (Alice),
and rate limiting (Alice). The pattern moved from
direct env access to centralized configuration.Workflow 3: Bug Investigation
When debugging, trace when a bug was introduced:
You: When was the function processPayment last changed,
and by whom? I think there's a bug.
Claude: Let me trace the history of processPayment...
**Git Blame for processPayment():**
| Line | Author | Date | Commit | Content |
|------|--------|---------|---------|------------------------|
| 45 | Alice | Dec 18 | abc123 | async function process |
| 46 | Bob | Dec 20 | def456 | const amount = ... |
| 47 | Bob | Dec 20 | def456 | if (amount < 0) { |
| 48 | Bob | Dec 20 | def456 | return false; | ⚠️
| 49 | Alice | Dec 18 | abc123 | } |
**Analysis:**
Bob's commit (def456) on Dec 20 added the negative
amount check on lines 46-48.
**Potential Issue:**
Line 48 returns `false` but the function should probably
throw an error or return an error object. This could cause
silent failures.
Would you like me to show the full diff from def456?Workflow 4: Branch Comparison
Before merging, understand what’s different:
You: Compare feature/new-auth with main and summarize
what would be merged
Claude: Comparing feature/new-auth to main...
**Branch: feature/new-auth**
- Ahead of main by: 12 commits
- Behind main by: 3 commits (may need rebase)
**Files Changed:**
| File | Changes | Type |
|-------------------------|----------------|----------|
| src/auth/login.ts | +156, -34 | Modified |
| src/auth/session.ts | +89, -12 | Modified |
| src/auth/mfa.ts | +234 | Added |
| src/types/auth.ts | +45, -8 | Modified |
| tests/auth/*.ts | +312, -45 | Modified |
**Summary of Changes:**
1. **New MFA support** - Added multi-factor authentication
2. **Session improvements** - Extended session handling
3. **Login refactor** - Better error messages and validation
4. **Type updates** - New types for MFA flow
**Merge Considerations:**
- Needs rebase onto latest main
- 312 lines of new tests (good coverage)
- Breaking change: session token format changedWorkflow 5: Codebase Exploration
When joining a new project:
You: Help me understand this repository. Show me the recent
activity, main contributors, and most-changed files.
Claude: Analyzing repository...
**Repository Overview:**
**Recent Activity (Last 30 days):**
- 47 commits
- 5 active contributors
- 23 files changed
**Top Contributors:**
| Author | Commits | Lines Changed |
|--------|---------|---------------|
| Alice | 18 | +1,234 / -456 |
| Bob | 15 | +987 / -234 |
| Carol | 8 | +567 / -123 |
| Dave | 4 | +234 / -89 |
| Eve | 2 | +45 / -12 |
**Most Active Areas:**
1. src/api/ - 156 changes (API development)
2. tests/ - 89 changes (testing focus)
3. src/components/ - 67 changes (UI work)
**Recent Major Changes:**
- Dec 20: Authentication overhaul (Alice)
- Dec 15: API v2 migration (Bob)
- Dec 10: Component library update (Carol)
Would you like me to dive deeper into any area?Example Prompts
Status & Working Tree
# Basic status
"What's the current git status?"
"Show me modified files"
"Do I have any uncommitted changes?"
# Staged changes
"What's staged for commit?"
"Show the diff of staged files"
"Am I ready to commit?"
# Comparisons
"What changed since my last commit?"
"Show differences from yesterday"
"Compare my working tree to HEAD"Commit History
# Recent history
"Show last 5 commits"
"What were today's commits?"
"Show commits from this week"
# Specific searches
"Find commits by Alice"
"Search for commits mentioning 'bug fix'"
"When was the login feature added?"
# Detailed views
"Show details of commit abc123"
"What files changed in the last commit?"
"Show the diff for commit def456"Understanding Code
# Blame/attribution
"Who wrote the validatePayment function?"
"When was this line last changed?"
"Show git blame for config.ts"
# File history
"Show history of changes to this file"
"How has app.ts evolved over time?"
"List all commits that touched utils/"
# Investigation
"When was this bug introduced?"
"Find the commit that broke authentication"
"Trace the history of this function"Branch Operations
# Listing
"What branches exist?"
"Which branch am I on?"
"Show remote branches"
# Comparisons
"Compare main and develop"
"What's different in feature/x?"
"How many commits ahead is my branch?"
# Analysis
"What would be merged from feature/auth?"
"Is this branch up to date with main?"
"Show commits unique to this branch"Code Review Support
# Pre-commit review
"Review my uncommitted changes for issues"
"Are there any debug statements I should remove?"
"Check my changes for security issues"
# Understanding changes
"Explain what changed in the last commit"
"Summarize the diff in plain English"
"What does this commit do?"
# Documentation
"Generate a commit message for my changes"
"Summarize changes for the changelog"
"What should I mention in the PR description?"For tips on prompting AI effectively, see the Prompt Engineering Fundamentals guide.
Advanced Configuration
SSH vs HTTPS Repos
Git MCP works with both:
# SSH remote
git@github.com:user/repo.git
# HTTPS remote
https://github.com/user/repo.gitNo special configuration needed - just point to the local repository path.
Performance Options
For large repositories, limit operations:
You: Show commits from the last week only
Claude: Filtering to recent history...
[More efficient than full log]Combining with Filesystem
For full codebase understanding:
{
"mcpServers": {
"git": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-git",
"--repository", "/projects/my-app"]
},
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem",
"/projects/my-app"]
}
}
}Now AI can:
- Read current file contents (Filesystem)
- See what changed (Git diff)
- Understand history (Git log)
Troubleshooting
Issue: “Not a git repository”
Symptoms: Server fails to start
Solutions:
| Cause | Solution |
|---|---|
| Wrong path | Verify repository path exists |
| No .git folder | Initialize with git init |
| Path is file, not directory | Use directory containing .git |
Issue: “Could not find git”
Symptoms: Git commands fail
Solutions:
| Cause | Solution |
|---|---|
| Git not installed | Install Git |
| Git not in PATH | Add Git to system PATH |
| Wrong Git binary | Check which git |
Issue: “Permission denied”
Symptoms: Can’t read repository
Solutions:
| Cause | Solution |
|---|---|
| File permissions | Check directory permissions |
| Repository owned by root | Use appropriate user |
| SELinux/AppArmor | Check security policies |
Issue: “Operation taking too long”
Symptoms: Slow responses for history
Solutions:
- Use
--max-countfor log operations - Limit date ranges
- Avoid full repository scans
- Be specific about files/paths
You: Show only the last 10 commits on src/api/
Claude: [More efficient than full log]Combining with Other MCPs
Git + Filesystem
Read code and understand changes:
You: Read the current auth.ts and show me what changed
in the last commit
Claude: [Uses Filesystem to read current code]
[Uses Git to show diff]
Current file is 234 lines.
Last commit (abc123) changed:
- Added rate limiting (lines 45-67)
- Updated error messages (lines 89-95)Git + GitHub
Local understanding + remote actions:
You: Review my local changes and create a PR if they look good
Claude: [Uses Git to review local changes]
[Uses GitHub to create PR]
Reviewed changes: ✅ Looking good
Created PR #45: "Add rate limiting to auth endpoints"Git + Memory
Remember repository context:
You: Remember the structure and patterns in this repository
Claude: [Uses Git to analyze history]
[Uses Memory to store patterns]
I've memorized:
- Branching strategy (git-flow)
- Main contributors
- Hot areas of development
- Commit message patternsSecurity Considerations
Read-Only by Default
Git MCP is read-only for safety:
| ✅ Can Do | ❌ Cannot Do |
|---|---|
| View status | Create commits |
| Read diffs | Push changes |
| Browse history | Merge branches |
| View branches | Delete branches |
| Search commits | Reset/revert |
Repository Access
| Best Practice | Why |
|---|---|
| Point to specific repos | Don’t expose all projects |
| Use project-level config | Scope per workspace |
| Avoid sensitive repos | Keep credentials repos private |
For more on AI security, see the Understanding AI Safety, Ethics, and Limitations guide.
What’s Visible
AI can see:
- All committed code and history
- Commit messages and authors
- Branch names and structure
- File changes and diffs
AI cannot see:
- Git credentials
- SSH keys
- Remote authentication
- Other directories
Related MCP Servers
| Server | Complements Git By… |
|---|---|
| GitHub MCP | Remote repository management |
| Filesystem MCP | Reading current file contents |
| Memory MCP | Remembering repository patterns |
| Slack MCP | Sharing commit summaries |
Summary
The Git MCP Server enables AI to understand your local repositories:
- ✅ Read-only access for safe exploration
- ✅ Full history via log, blame, show
- ✅ Change analysis via status and diff
- ✅ Branch comparison for merge planning
- ✅ Works with any Git repo regardless of remote
- ✅ Universal AI support - Claude, ChatGPT, Copilot, Gemini
2025 Updates:
- Part of Agentic AI Foundation (Linux Foundation)
- Protocol version 2025-11-25 with enhanced context
- GitMCP: Remote MCP endpoints for any GitHub project
- Works with all major AI coding assistants
Best use cases:
- Pre-commit code review
- Understanding code history
- Bug investigation via blame
- Onboarding to new codebases
- Branch comparison before merge
Pro tip: Combine with GitHub MCP for complete workflow:
- Git MCP → Understand local changes
- GitHub MCP → Create PRs and manage remote
Next: Learn about Memory MCP Server → for persistent AI context.
Questions about Git MCP? Check the source code on GitHub or explore GitMCP for remote access.