Git MCP Server

A Model Context Protocol (MCP) server for local Git operations with security and validation.

Features

🔒 Secure: Path traversal protection and input validation
✅ Validated: Runtime Zod validation for all inputs
⏱️ Timeout Protection: Configurable timeouts prevent indefinite blocking
🛠️ Complete: 15 Git operations supported
📝 Well-tested: Comprehensive integration test suite

Available Tools

git_clone: Clone a Git repository
git_status: Get the status of the repository
git_diff: Get the diff of the repository (supports staged files)
git_list_branches: List local and remote branches
git_checkout: Switch between branches and update files
git_list_files: List files in the repository
git_read_file: Read the content of a file (with path traversal protection)
git_add: Add files to the staging area
git_reset: Reset current HEAD to the specified state (supports soft, mixed, hard)
git_pull: Pull changes from remote (uses rebase)
git_commit: Commit changes to the repository
git_push: Push changes to remote (automatically performs pull --rebase first)
git_log: Get the commit log of the repository
git_create_branch: Create a new branch (optionally from a specific starting point)
git_merge: Merge a branch into the current branch (supports --no-ff)

Setup

Install dependencies:

   npm install

Build:

   npm run build

Run:

   npm run start

Configuration Examples

Claude Desktop

{
  "mcpServers": {
    "git-mcp-server": {
      "command": "node",
      "args": ["/absolute/path/to/git-context-mcp/dist/index.js"]
    }
  }
}

Cline / Windsurf

{
  "mcpServers": {
    "git-mcp-server": {
      "command": "npx",
      "args": ["-y", "git-mcp-server"]
    }
  }
}

Usage Examples

Clone a Repository

{
  "tool": "git_clone",
  "arguments": {
    "repoUrl": "https://github.com/user/repo.git",
    "localPath": "/path/to/local/repo"
  }
}

Read a File

{
  "tool": "git_read_file",
  "arguments": {
    "repoPath": "/path/to/repo",
    "filePath": "src/index.ts"
  }
}

Create and Checkout a Branch

{
  "tool": "git_create_branch",
  "arguments": {
    "repoPath": "/path/to/repo",
    "branch": "feature/new-feature",
    "checkout": true
  }
}

Security

Path Traversal Protection: File paths are validated to prevent access outside the repository
Input Validation: All inputs are validated with Zod schemas before processing
Error Handling: Proper error context preservation throughout the stack
Timeout Protection: Operations have configurable timeouts (30s default, 60s for clone)

Testing

Run the integration test suite to verify all Git tools work correctly:

npx tsx test_script.ts

The script creates temporary local repositories, exercises all 15 tools plus error handling scenarios, and cleans up automatically.

Troubleshooting

Error: "Path does not exist"

Ensure the repository path exists and is accessible.

Error: "File path must be within the repository"

The requested file path is outside the repository boundaries. This is a security feature to prevent directory traversal attacks.

Timeout errors

Operations have a 30-second timeout by default (60 seconds for clone). For very large repositories or slow networks, operations may timeout. This is a safety feature to prevent indefinite blocking.

Error: "Git pull --rebase failed"

The rebase was automatically aborted to restore the repository to a clean state. Check for uncommitted changes or conflicts.

Development

Running Tests

npx tsx test_script.ts

Building

npm run build

Watching for Changes

npm run watch

Prerequisites

Node.js 18+
Git

License

MIT

git-context-mcp