MCP Git Commit Generator

Generate conventional commit messages from your staged git changes using Model Context Protocol (MCP).

✨ Features

• 🤖 Automatic commit message generation based on staged git diffs
• 📝 Conventional Commits support with auto-detection of type and scope
• 🔄 Multiple transport options - stdio (default) and SSE for different use cases
• 🔍 Inspector UI for interactive testing and debugging
• 🐳 Docker support with pre-built images for easy deployment
• ⚡ Cross-platform - works on macOS, Linux, and Windows

📦 Requirements

• For Docker usage: Docker (for running the server in a container)
• For PyPI/uvx usage: Python >= 3.13.5 and uv (recommended) or pip
• Git (for version control)
• An MCP-compatible client (VS Code with MCP extension, Claude Desktop, Cursor, Windsurf, etc.)

🚀 Installation

You can install and use the MCP Git Commit Generator in multiple ways:

Option 1: Using uvx (Recommended)

The easiest way to use the package is with uvx, which automatically manages the virtual environment:

uvx mcp-git-commit-generator

Option 2: Install from PyPI

pip install mcp-git-commit-generator

Or with uv:

uv pip install mcp-git-commit-generator

Option 3: Using Docker

Use the pre-built Docker image from GitHub Container Registry (no installation required):

docker run -i --rm --mount type=bind,src=${HOME},dst=${HOME} ghcr.io/theoklitosbam7/mcp-git-commit-generator:latest

🛠️ Available Tools

This MCP server provides the following tools to help you generate conventional commit messages:

generate_commit_message

Generates a conventional commit message based on your staged git changes.

Parameters:

• repo_path (string, optional): Path to the git repository. If omitted, uses the current directory.
• commit_type (string, optional): Conventional commit type (e.g., feat, fix, docs, style, refactor, perf, build, ci, test, chore, revert). If omitted, the type will be auto-detected.
• scope (string, optional): Scope of the change (e.g., file or module name). If omitted, the scope will be auto-detected based on changed files.

Usage:

1. Stage your changes: git add <files>
2. Use the tool through your MCP client to generate a commit message
3. The tool will analyze your staged changes and generate an appropriate conventional commit message

check_git_status

Checks the current git repository status, including staged, unstaged, and untracked files.

Parameters:

• repo_path (string, optional): Path to the git repository. If omitted, uses the current directory.

Usage:

Use this tool to get an overview of your current git repository state before generating commit messages.

🧩 MCP Client Configuration

Configure the MCP Git Commit Generator in your favorite MCP client. You have multiple options:

1. Using uvx (recommended - automatically manages dependencies)
2. Using Docker (no local Python installation required)
3. Using local Python installation (for development)

VS Code

Add one of the following configurations to your VS Code mcp.json file (usually located at .vscode/mcp.json in your workspace):

Using uvx (Recommended)

{
  "servers": {
    "mcp-git-commit-generator": {
      "command": "uvx",
      "args": ["mcp-git-commit-generator"]
    }
  }
}

Using Docker

{
  "servers": {
    "mcp-git-commit-generator": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount",
        "type=bind,src=${userHome},dst=${userHome}",
        "ghcr.io/theoklitosbam7/mcp-git-commit-generator:latest"
      ]
    }
  }
}

If you want to put the configuration in your user settings.json file, you can do so by adding:

{
  "mcp": {
    "servers": {
      "mcp-git-commit-generator": {
        "command": "uvx",
        "args": ["mcp-git-commit-generator"]
      }
    }
  }
}

Cursor

Add one of the following to your Cursor MCP configuration file (usually located at ~/.cursor/mcp.json):

Cursor with uvx (Recommended)

{
  "mcpServers": {
    "mcp-git-commit-generator": {
      "command": "uvx",
      "args": ["mcp-git-commit-generator"]
    }
  }
}

Cursor with Docker

{
  "mcpServers": {
    "mcp-git-commit-generator": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount",
        "type=bind,src=${userHome},dst=${userHome}",
        "ghcr.io/theoklitosbam7/mcp-git-commit-generator:latest"
      ]
    }
  }
}

Windsurf

Configure Windsurf with one of the following MCP server settings (usually located at ~/.codeium/windsurf/mcp_config.json):

Windsurf with uvx (Recommended)

{
    "mcpServers": {
      "mcp-git-commit-generator": {
        "command": "uvx",
        "args": ["mcp-git-commit-generator"]
      }
    }
}

Windsurf with Docker

{
    "mcpServers": {
      "mcp-git-commit-generator": {
        "command": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "--mount",
          "type=bind,src=${userHome},dst=${userHome}",
          "ghcr.io/theoklitosbam7/mcp-git-commit-generator:latest"
        ]
      }
    }
}

Claude Desktop

Add one of the following to your Claude Desktop configuration file (usually located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

Claude Desktop with uvx (Recommended)

{
  "mcpServers": {
    "mcp-git-commit-generator": {
      "command": "uvx",
      "args": ["mcp-git-commit-generator"]
    }
  }
}

Claude Desktop with Docker

{
  "mcpServers": {
    "mcp-git-commit-generator": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount",
        "type=bind,src=${userHome},dst=${userHome}",
        "ghcr.io/theoklitosbam7/mcp-git-commit-generator:latest"
      ]
    }
  }
}

Note: The --mount option in Docker configurations allows the Docker container to access your home directory, enabling it to work with git repositories located anywhere in your file system. When using uvx or pip installations, this mounting is not needed as the tool runs directly on your system. Adjust the mount path if your repositories are located elsewhere when using Docker.

🚀 Quick Start Guide

1. Install the package using one of the methods above:

   • Recommended: uvx mcp-git-commit-generator (or configure in your MCP client)
   • Alternative: pip install mcp-git-commit-generator
   • Docker: Use the configurations above with Docker

2. Configure your MCP client using one of the configurations above

3. Stage some changes in a git repository:

   git add <files>
   

4. Use the tools through your MCP client:

   • Use check_git_status to see your current repository state
   • Use generate_commit_message to create a conventional commit message

5. Commit your changes with the generated message

---

👨‍💻 Developer Guidelines

The following sections are intended for developers who want to contribute to or modify the MCP Git Commit Generator.

Local Development Setup 🛠️

If you prefer not to use Docker for development, you can run the server locally:

Requirements:

• Python >= 3.13.5
• uv (recommended for dependency management and local development)
• Node.js (for Inspector UI, optional)
• Python Debugger Extension (for debugging, optional)

Note: The MCP CLI dependency is automatically installed via uv.lock when using uv sync.

Installation:

1. Clone the repository:

   git clone https://github.com/theoklitosBam7/mcp-git-commit-generator.git
   cd mcp-git-commit-generator
   

2. Prepare environment:

   There are two approaches to set up the environment for this project. You can choose either one based on your preference.

   Note: Reload VSCode or terminal to ensure the virtual environment python is used after creating the virtual environment.

   Approach	Steps
   Using uv (Recommended)	1. Create virtual environment and install dependencies: uv sync --group dev <br>2. Run VSCode Command "Python: Select Interpreter" and select the python from .venv directory <br>3. The project is installed in editable mode automatically by uv sync.
   Using pip	1. Create virtual environment: python -m venv .venv <br>2. Run VSCode Command "Python: Select Interpreter" and select the python from created virtual environment <br>3. Install dependen

---