Git Workflow Automation MCP Server

A Model Context Protocol (MCP) server that provides automated Git workflow tools for committing, creating pull requests, and merging with proper GitHub authentication handling.

Features

• Automated Git Operations: Commit, push, create PRs, and merge in one command

• GitHub Authentication Handling: Automatically clears problematic environment tokens

• Dry Run Support: Test operations before executing them

• Conventional Commits: Supports proper commit message formatting

• Branch Management: Automatic branch creation and switching

• Error Handling: Comprehensive error reporting and rollback capabilities

Related MCP server: GitHub MCP Server

Available Tools

1. git_commit_and_push

Commits staged changes and pushes to remote repository.

Parameters:

• files (array, optional): File paths to commit (empty for all changes)

• commitMessage (string, required): Commit message (use conventional format)

• branch (string, optional): Branch name to create/switch to

• workingDir (string, optional): Working directory path

• dryRun (boolean, optional): Preview without executing

Example:

use_mcp_tool("git-workflow", "git_commit_and_push", {
  "files": ["src/app.ts", "README.md"],
  "commitMessage": "feat: add new authentication system",
  "branch": "feature/auth-system",
  "dryRun": true
})

2. create_pull_request

Creates a GitHub pull request with proper authentication handling.

Parameters:

• title (string, required): Pull request title

• body (string, required): Pull request description

• baseBranch (string, optional): Base branch (default: "main")

• headBranch (string, optional): Head branch (defaults to current)

• workingDir (string, optional): Working directory path

• dryRun (boolean, optional): Preview without executing

Example:

use_mcp_tool("git-workflow", "create_pull_request", {
  "title": "Feature: User Authentication System",
  "body": "Implements comprehensive user authentication with JWT tokens and OAuth2 support",
  "baseBranch": "main",
  "headBranch": "feature/auth-system"
})

3. merge_pull_request

Merges a GitHub pull request.

Parameters:

• prNumber (string, required): Pull request number

• mergeMethod (string, optional): "merge", "squash", or "rebase" (default: "merge")

• deleteBranch (boolean, optional): Delete branch after merge (default: true)

• workingDir (string, optional): Working directory path

• dryRun (boolean, optional): Preview without executing

Example:

use_mcp_tool("git-workflow", "merge_pull_request", {
  "prNumber": "42",
  "mergeMethod": "squash",
  "deleteBranch": true
})

4. complete_git_workflow

Executes the complete Git workflow: commit, push, create PR, and optionally merge.

Parameters:

• files (array, optional): Files to commit

• commitMessage (string, required): Commit message (conventional format)

• prTitle (string, required): Pull request title

• prBody (string, required): Pull request description

• branch (string, optional): Feature branch name

• baseBranch (string, optional): Base branch (default: "main")

• autoMerge (boolean, optional): Automatically merge PR (default: false)

• workingDir (string, optional): Working directory path

• dryRun (boolean, optional): Preview without executing

Example:

use_mcp_tool("git-workflow", "complete_git_workflow", {
  "files": ["src/**/*.ts", "docs/**/*.md"],
  "commitMessage": "feat(auth): implement OAuth2 authentication",
  "prTitle": "Feature: OAuth2 Authentication System",
  "prBody": "Adds comprehensive OAuth2 authentication with Google and GitHub providers",
  "branch": "feature/oauth2-auth",
  "autoMerge": false,
  "dryRun": true
})

Installation

Quick Setup

1. Clone the Repository

   git clone https://github.com/Arcia125/git-workflow-mcp-server.git
   cd git-workflow-mcp-server

2. Install Dependencies

   npm install

3. Build the Server

   npm run build

4. Add to MCP Configuration

   Add the server to your MCP client settings file:

   {
     "mcpServers": {
       "git-workflow": {
         "command": "node",
         "args": ["/path/to/git-workflow-mcp-server/build/index.js"],
         "disabled": false,
         "alwaysAllow": [],
         "disabledTools": []
       }
     }
   }

Alternative: NPM Global Install (Coming Soon)

Future versions will support global npm installation:

npm install -g git-workflow-mcp-server

Configuration Paths

Common MCP Settings Locations:

• Roo-Code: %APPDATA%/Code - Insiders/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json

• Claude Desktop: %APPDATA%/Claude/claude_desktop_config.json

• Other MCP Clients: Check your client's documentation for settings location

Verify Installation

Test the installation with a dry run:

use_mcp_tool("git-workflow", "git_commit_and_push", {
  "files": ["README.md"],
  "commitMessage": "test: verify MCP server installation",
  "dryRun": true
})

Prerequisites

• Node.js installed

• Git configured with remote repository

• GitHub CLI (gh) installed and authenticated

• Proper GitHub repository permissions

Authentication

The server automatically handles GitHub authentication issues by:

1. Clearing problematic environment tokens (GITHUB_TOKEN, GH_TOKEN)

2. Using PowerShell commands for reliable token management

3. Relying on GitHub CLI keyring authentication

4. Providing detailed error messages for authentication failures

Best Practices

1. Always Use Dry Run First

// Test the operation first
use_mcp_tool("git-workflow", "complete_git_workflow", {
  "commitMessage": "feat: add new feature",
  "prTitle": "New Feature",
  "prBody": "Description",
  "dryRun": true
})

// Then execute after confirmation
use_mcp_tool("git-workflow", "complete_git_workflow", {
  "commitMessage": "feat: add new feature",
  "prTitle": "New Feature",
  "prBody": "Description",
  "dryRun": false
})

2. Use Conventional Commits

// Good commit messages:
"feat(auth): add OAuth2 integration"
"fix(ui): resolve button alignment issue"
"docs(api): update endpoint documentation"
"refactor(utils): simplify date formatting"

3. Meaningful PR Titles and Descriptions

{
  "prTitle": "Feature: OAuth2 Authentication System",
  "prBody": "## Changes\n- Implements OAuth2 with Google/GitHub\n- Adds JWT token management\n- Updates user authentication flow\n\n## Testing\n- All auth tests pass\n- Manual testing completed"
}

Error Handling

The server provides comprehensive error handling:

• Git Repository Errors: Validates repository state

• Authentication Failures: Handles GitHub CLI auth issues

• Network Issues: Provides clear error messages

• Branch Conflicts: Manages branch creation/switching

• Merge Conflicts: Reports merge issues clearly

Dependencies

• @modelcontextprotocol/sdk: MCP server framework

• simple-git: Git operations

• axios: HTTP requests (if needed)

• zod: Schema validation

Development

To modify the server:

1. Edit src/index.ts

2. Run npm run build

3. Restart your MCP client

Support

For issues or questions:

• Check GitHub CLI authentication: gh auth status

• Verify repository permissions

• Review error messages for specific guidance

• Test with dry run mode first

Version

Version 0.1.0 - Initial release with core Git workflow automation features.