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
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 toworkingDir(string, optional): Working directory pathdryRun(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 titlebody(string, required): Pull request descriptionbaseBranch(string, optional): Base branch (default: "main")headBranch(string, optional): Head branch (defaults to current)workingDir(string, optional): Working directory pathdryRun(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 numbermergeMethod(string, optional): "merge", "squash", or "rebase" (default: "merge")deleteBranch(boolean, optional): Delete branch after merge (default: true)workingDir(string, optional): Working directory pathdryRun(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 commitcommitMessage(string, required): Commit message (conventional format)prTitle(string, required): Pull request titleprBody(string, required): Pull request descriptionbranch(string, optional): Feature branch namebaseBranch(string, optional): Base branch (default: "main")autoMerge(boolean, optional): Automatically merge PR (default: false)workingDir(string, optional): Working directory pathdryRun(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
-
Clone the Repository
git clone https://github.com/Arcia125/git-workflow-mcp-server.git cd git-workflow-mcp-server -
Install Dependencies
npm install -
Build the Server
npm run build -
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:
- Clearing problematic environment tokens (
GITHUB_TOKEN,GH_TOKEN) - Using PowerShell commands for reliable token management
- Relying on GitHub CLI keyring authentication
- 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 frameworksimple-git: Git operationsaxios: HTTP requests (if needed)zod: Schema validation
Development
To modify the server:
- Edit
src/index.ts - Run
npm run build - 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.