@nvhien20vn/git-mcp-server

v0.0.1

Published

a year ago

mcp for git

Git MCP Server

An MCP (Model Context Protocol) server providing tools to interact with Git repositories. Enables LLMs and AI agents to perform Git operations like clone, commit, push, pull, branch, diff, log, status, and more via the MCP standard.

Built on the nvhien20vn/mcp-ts-template, this server follows a modular architecture:

Developer Note: This repository includes a .clinerules file that serves as a developer cheat sheet for your LLM coding agent with quick reference for the codebase patterns, file locations, and code snippets.

| Overview | Features | Installation |

| Configuration | Project Structure |

Overview

Empower your AI agents and development tools with seamless Git integration!

The Git MCP Server acts as a bridge, allowing applications (MCP Clients) that understand the Model Context Protocol (MCP) – like advanced AI assistants (LLMs), IDE extensions, or custom scripts – to interact directly and safely with local Git repositories.

Instead of complex scripting or manual CLI, your tools can leverage this server to:

Automate Git workflows: Clone repositories, create branches, stage changes, commit work, push updates, and manage tags programmatically.
Gain repository insights: Check status, view logs, diff changes, and inspect Git objects without leaving the host application.
Integrate Git into AI-driven development: Enable LLMs to manage version control as part of their coding or refactoring tasks.

Built on the robust mcp-ts-template, this server provides a standardized, secure, and efficient way to expose Git functionality via the MCP standard. It achieves this by securely executing the standard git command-line tool installed on the system using Node.js's child_process module, ensuring compatibility and leveraging the full power of Git.

Features

Core Utilities (from Template)

Leverages the robust utilities provided by the mcp-ts-template:

Logging: Structured, configurable logging (file rotation, console, MCP notifications) with sensitive data redaction.
Error Handling: Centralized error processing, standardized error types (McpError), and automatic logging.
Configuration: Environment variable loading (dotenv).
Input Validation/Sanitization: Uses zod for schema validation and custom sanitization logic (crucial for paths).
Request Context: Tracking and correlation of operations via unique request IDs.
Type Safety: Strong typing enforced by TypeScript and Zod schemas.
HTTP Transport Option: Built-in Express server with SSE, session management, and CORS support.

Git Operations

Direct Git CLI Execution: Interacts with Git by securely executing the standard git command-line tool via Node.js child_process, ensuring full compatibility and access to Git's features.
Comprehensive Command Coverage: Exposes a wide range of Git commands as MCP tools (see Tools section).
Repository Interaction: Supports status checking, branching, staging, committing, fetching, pulling, pushing, diffing, logging, resetting, tagging, and more.
Working Directory Management: Allows setting and clearing a session-specific working directory for context persistence across multiple Git operations.
Safety Features: Includes checks and requires explicit confirmation for potentially destructive operations like git clean and git reset --hard.
Commit Signing: Supports GPG or SSH signing for verified commits, controlled via the GIT_SIGN_COMMITS environment variable and server-side Git configuration. Includes an optional tool parameter to fall back to unsigned commits on signing failure.

Installation

Prerequisites

Node.js (>=18.0.0)
npm (comes with Node.js)
Git installed and accessible in the system PATH.

Install via npm

Install the package globally:
```
npm install @nvhien20vn/git-mcp-server
```

Install from Source

Clone the repository:

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

Install dependencies:
```
npm install
```
Build the project:
```
npm run build (or `npm run rebuild`)
```
This compiles the TypeScript code to JavaScript in the dist/ directory and makes the entry point executable.

Configuration

Environment Variables

Configure the server using environment variables. Create a .env file in the project root (copy from .env.example) or set them in your environment.

| Variable | Description | Default | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | MCP_TRANSPORT_TYPE | Transport mechanism: stdio or http. | stdio | | MCP_HTTP_PORT | Port for the HTTP server (if MCP_TRANSPORT_TYPE=http). Retries next ports if busy. | 3010 | | MCP_HTTP_HOST | Host address for the HTTP server (if MCP_TRANSPORT_TYPE=http). | 127.0.0.1 | | MCP_ALLOWED_ORIGINS | Comma-separated list of allowed origins for CORS (if MCP_TRANSPORT_TYPE=http). | (none) | | MCP_LOG_LEVEL | Logging level (debug, info, notice, warning, error, crit, alert, emerg). Inherited from template. | info | | GIT_SIGN_COMMITS | Set to "true" to enable signing attempts for commits made by the git_commit tool. Requires server-side Git/key setup (see below). | false | | MCP_AUTH_SECRET_KEY | Secret key for signing/verifying authentication tokens (required if auth is enabled in the future). | '' |

MCP Client Settings

Add to your MCP client settings (e.g., cline_mcp_settings.json):

{
  "mcpServers": {
    "git-mcp-server": {
      // Use a descriptive name
      "command": "node", // Use node to run the script
      "args": ["/path/to/your/git-mcp-server/dist/index.js"], // Absolute path to the built entry point
      "env": {
        // "MCP_TRANSPORT_TYPE": "http", // Optional: if using http
        // "MCP_HTTP_PORT": "3010",     // Optional: if using http and non-default port
        // "GIT_SIGN_COMMITS": "true"   // Optional: Enable commit signing attempts if server is configured
      },
      "disabled": false,
      "autoApprove": [] // Configure auto-approval rules if desired
    }
  }
}

Note: You can see mcp.json for an example MCP client configuration file that includes the Git MCP Server.*

Project Structure

The codebase follows a modular structure within the src/ directory:

src/
├── index.ts           # Entry point: Initializes and starts the server
├── config/            # Configuration loading (env vars, package info)
│   └── index.ts
├── mcp-server/        # Core MCP server logic and capability registration
│   ├── server.ts      # Server setup, capability registration
│   ├── transports/    # Transport handling (stdio, http)
│   ├── resources/     # MCP Resource implementations (currently none)
│   └── tools/         # MCP Tool implementations (subdirs per tool)
├── types-global/      # Shared TypeScript type definitions
└── utils/             # Common utility functions (logger, error handler, etc.)

For a detailed file tree, run npm run tree or see docs/tree.md.

Tools

The Git MCP Server provides a suite of tools for interacting with Git repositories, callable via the Model Context Protocol.

Note: The path parameter for most tools defaults to the session's working directory if set via git_set_working_dir.

Development

Build and Test

# Build the project (compile TS to JS in dist/ and make executable)
npm run build

# Test the server locally using the MCP inspector tool (stdio transport)
npm run inspector

# Test the server locally using the MCP inspector tool (http transport)
npm run inspector:http

# Clean build artifacts (runs scripts/clean.ts)
npm run clean

# Generate a file tree representation for documentation (runs scripts/tree.ts)
npm run tree

# Clean build artifacts and then rebuild the project
npm run rebuild

# Start the server using stdio (default)
npm start
# Or explicitly:
npm run start:stdio

# Start the server using HTTP transport
npm run start:http

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.