GIT MCP Server

Node.js server implementing Model Context Protocol (MCP) for git operations.

Features

• Git repository management through MCP protocol
• Support for common Git operations
• Type-safe command execution with Zod schema validation
• Robust error handling with detailed git error messages
• Comprehensive test suite covering all operations

API

The server provides the following Git operations:

git_clone

Clone a git repository to a local directory.

{
    repository: string;    // Git repository URL to clone
    directory?: string;    // Target directory for the repository
    branch?: string;       // Branch to checkout
}

git_status

Get the status of a git repository, showing changed files and branch information.

{
    repository_path: string;  // Path to the git repository
}

git_pull

Pull changes from a remote repository into your local repository.

{
    repository_path: string;  // Path to the git repository
    remote?: string;         // Remote name
    branch?: string;         // Branch name
}

git_push

Push local changes to a remote repository.

{
    repository_path: string;  // Path to the git repository
    remote?: string;         // Remote name
    branch?: string;         // Branch name
}

git_commit

Commit changes to the repository with a message.

{
    repository_path: string;  // Path to the git repository
    message: string;         // Commit message
    add_all?: boolean;       // Add all files before committing
}

git_checkout

Checkout a branch or specific commit.

{
    repository_path: string;  // Path to the git repository
    branch: string;          // Branch or commit to checkout
    create?: boolean;        // Create new branch if it does not exist
}

git_log

Show commit history.

{
    repository_path: string;  // Path to the git repository
    count?: number;          // Number of commits to show
}

git_branch

List all branches in the repository.

{
    repository_path: string;  // Path to the git repository
    show_remote?: boolean;   // Show remote branches as well
}

git_add

Add files to the staging area.

{
    repository_path: string;  // Path to the git repository
    files: string[];         // Files to add to the staging area
}

git_init

Initialize a new git repository.

{
    repository_path: string;  // Path for the new git repository
    bare?: boolean;          // Create a bare repository
}

git_remote

Manage remote repositories.

{
    repository_path: string;  // Path to the git repository
    action: 'add' | 'remove' | 'set-url' | 'list';  // Action to perform on remote
    name?: string;           // Name of the remote
    url?: string;            // URL of the remote repository
}

Error Handling

The server provides robust error handling for git operations:

• All git commands are executed with proper error capturing
• Error messages are cleaned and formatted for improved readability
• Specific git error patterns are detected and extracted from command output
• Each tool returns structured error responses with isError: true flag
• Errors include descriptive messages that match standard git error formats

Installation

npm install
npm run build

Usage

The server can be run using:

npm start

Or directly using the built executable:

./dist/index.js

Testing

The project includes a comprehensive test suite that verifies all git operations work correctly. To run the tests:

npm test

The tests:

• Create a temporary git repository
• Test the full git workflow (clone, branch, add, commit, etc.)
• Verify proper error handling for invalid operations
• Clean up resources after test execution

For continuous test development, you can also use:

npm run test:watch

Docker

A Docker image is available for easy deployment:

docker build -t mcp-git .
docker run mcp-git

Development

npm run dev  # Start development mode with watch
npm run build  # Build the project

Using with Cursor AI Chat

For detailed instructions on using this Git MCP server with Cursor's AI assistant, please see using with cursor.

License

MIT