Git Workflow MCP Server

A Model Context Protocol (MCP) server that provides Git workflow tools over HTTP. This server enables AI assistants like Cursor, Claude, and ChatGPT to interact with local Git repositories and optionally with GitHub via the API.

Features

Local Git Tools (No GitHub Token Required)

• git_status - Get current Git status including branch, ahead/behind counts, and file lists
• git_log - View commit history with author, date, and messages
• git_diff - Show diff for specific files
• git_list_branches - List all branches and show current branch
• git_stage_files - Stage files for commit
• git_commit - Create commits with messages
• git_checkout_branch - Checkout branches (with optional creation)

GitHub Tools (Requires GITHUB_TOKEN)

• github_list_prs - List pull requests (open, closed, or all)
• github_create_pr - Create new pull requests
• github_comment_on_pr - Add comments to pull requests

Installation

1. Clone or download this repository
2. Install dependencies:

pip install -r requirements.txt

Configuration

Environment Variables

• GIT_MCP_REPO (optional): Path to the Git repository the MCP server should operate on. Defaults to the current working directory if not set.

• GITHUB_TOKEN (optional): GitHub personal access token. If set, enables GitHub API tools. If not set, GitHub tools will return an error indicating that GitHub integration is disabled.

Getting a GitHub Token

1. Go to GitHub Settings Developer settings Personal access tokens Tokens (classic)
2. Generate a new token with repo scope
3. Copy the token and set it as an environment variable

Running the Server

Basic Usage

export GIT_MCP_REPO=/path/to/your/git/repo
# Optional: export GITHUB_TOKEN=ghp_xxxxxxxxxxxx
uvicorn server:app --host 127.0.0.1 --port 3333

With Custom Host/Port

export MCP_HOST=0.0.0.0
export MCP_PORT=8080
uvicorn server:app --host 0.0.0.0 --port 8080

The server will be available at http://127.0.0.1:3333/mcp (or your custom host/port).

Configuring as an MCP Server

For Cursor

Add to your Cursor MCP settings (typically in ~/.cursor/mcp.json or similar):

{
  "mcpServers": {
    "git-workflow-mcp": {
      "command": "uvicorn",
      "args": ["server:app", "--host", "127.0.0.1", "--port", "3333"],
      "env": {
        "GIT_MCP_REPO": "/path/to/your/repo",
        "GITHUB_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    }
  }
}

Or if using HTTP transport directly:

{
  "mcpServers": {
    "git-workflow-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:3333/mcp",
      "env": {
        "GIT_MCP_REPO": "/path/to/your/repo",
        "GITHUB_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    }
  }
}

For Claude Desktop

Add to your Claude Desktop configuration (typically ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or similar location on other platforms):

{
  "mcpServers": {
    "git-workflow-mcp": {
      "url": "http://127.0.0.1:3333/mcp",
      "env": {
        "GIT_MCP_REPO": "/path/to/your/repo",
        "GITHUB_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    }
  }
}

Usage Examples

Example 1: Check Repository Status

Prompt: "Use your git tools to show me the status of my repo and summarize changes."

The AI will call git_status and provide a summary of:

• Current branch
• Ahead/behind counts
• Staged files
• Modified files
• Untracked files

Example 2: Stage and Commit Changes

Prompt: "Stage all modified files, generate a good commit message, and commit."

The AI will:

1. Call git_status to see what's modified
2. Call git_stage_files with the list of modified files
3. Generate an appropriate commit message
4. Call git_commit with the message

Example 3: View Recent Commits

Prompt: "Show me the last 5 commits with their authors and messages."

The AI will call git_log with limit=5 and format the results.

Example 4: List GitHub Pull Requests

Prompt: "List open PRs on GitHub for this repo and summarize them."

The AI will call github_list_prs with state="open" and provide a summary of all open pull requests.

Example 5: Create a Pull Request

Prompt: "Create a pull request for the current branch targeting main with title 'Add new feature'."

The AI will call github_create_pr with the appropriate parameters.

Important Notes

• Local Git tools work without any GitHub token - You can use all the Git operations (status, log, diff, stage, commit, checkout) without setting GITHUB_TOKEN.

• GitHub tools require GITHUB_TOKEN - The GitHub API tools (github_list_prs, github_create_pr, github_comment_on_pr) will only work when GITHUB_TOKEN is set. If the token is not set, these tools will return an error message indicating that GitHub integration is disabled.

• Repository must be a Git repository - The GIT_MCP_REPO path must point to a directory containing a .git folder. If it doesn't, Git operations will fail with a clear error message.

• File path validation - All file paths provided to Git tools are validated to ensure they are within the repository root for security.

Project Structure

git-workflow-mcp/
 server.py          # Main HTTP MCP server with FastAPI
 git_tools.py       # Local Git operations using subprocess
 github_tools.py    # GitHub API operations using requests
 config.py          # Configuration and environment variables
 requirements.txt   # Python dependencies
 README.md          # This file

Development

Testing Locally

1. Start the server:

export GIT_MCP_REPO=/path/to/test/repo
uvicorn server:app --host 127.0.0.1 --port 3333 --reload

1. Test the health endpoint:

curl http://127.0.0.1:3333/

1. Test MCP endpoint (example):

curl -X POST http://127.0.0.1:3333/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

License

This project is provided as-is for use with MCP-compatible AI assistants.

Troubleshooting

"No Git repository found"

• Ensure GIT_MCP_REPO points to a valid Git repository (contains .git folder)
• Or run the server from within a Git repository directory

"GitHub integration is disabled"

• Set the GITHUB_TOKEN environment variable
• Ensure the token has the repo scope
• Verify the repository has a GitHub remote configured (git remote get-url origin)

"Path is outside repository root"

• Ensure all file paths are relative to the repository root
• Do not use absolute paths or paths with .. that escape the repository