Git Workflow MCP Server

# 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: ```bash 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 ```bash 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 ```bash 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): ```json { "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: ```json { "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): ```json { "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: ```bash export GIT_MCP_REPO=/path/to/test/repo uvicorn server:app --host 127.0.0.1 --port 3333 --reload ``` 2. Test the health endpoint: ```bash curl http://127.0.0.1:3333/ ``` 3. Test MCP endpoint (example): ```bash 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