git-commit-message-mcp

AI-powered git commit message generator using Model Context Protocol (MCP).

Features

• 🤖 Generate commit messages using AI
• 🔀 Support for branch comparison
• 📝 Customizable prompt templates
• 🌍 Multi-language support (Chinese/English)
• ⚙️ Flexible configuration (project-level and global)

Built-in Prompts

The package includes 4 built-in prompt templates you can use out-of-the-box:

Prompt Name	Description	Language	Use Case
default	Default Conventional Commits style	Chinese	General use, Chinese teams
conventional	Standard Conventional Commits	English	Open source, English projects
simple	Concise one-line messages	Any	Quick commits, simple changes
detailed	Comprehensive What/Why/How format	Any	Complex features, detailed documentation

Location: These prompts are in the prompts/ directory of the npm package.

How to Use Built-in Prompts

In conversation:

• "Generate commit message" → Uses default
• "Use conventional prompt" → Uses conventional
• "Use simple prompt" → Uses simple
• "Use detailed prompt" → Uses detailed

Set as default via MCP config:

{
  "mcpServers": {
    "git-commit-message-mcp": {
      "command": "npx",
      "args": ["-y", "git-commit-message-mcp"],
      "env": {
        "DEFAULT_PROMPT_FILE": "conventional"
      }
    }
  }
}

Now "Generate commit message" uses conventional instead of default!

Set as default via config file:

{
  "defaultPromptFile": "simple"
}

Installation

npm install
npm run build

Quick Start

1. Configure MCP Server

Add to your Claude Desktop or Claude Code MCP configuration:

{
  "mcpServers": {
    "git-commit-message-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/git-commit-message-mcp/dist/index.js"]
    }
  }
}

For Claude Desktop, the config file is at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

For Claude Code:

• Use the MCP settings in your IDE

2. Use in Conversation

Scenario 1: Generate commit message for working directory

User: "Generate commit message"
AI: [Calls git_diff() → generate_commit_message_prompt() → Returns suggested commit message]

Scenario 2: Compare with a branch

User: "Compare with development branch and generate commit message"
AI: [Calls git_diff({compare: "development"}) → Returns commit message]

Scenario 3: Compare two branches

User: "Compare featureA with development branch, generate commit message"
AI: [Calls git_diff({base: "development", compare: "featureA"}) → Returns commit message]

Configuration

MCP Configuration (Recommended)

Configure via environment variables in your MCP server config:

{
  "mcpServers": {
    "git-commit-message-mcp": {
      "command": "npx",
      "args": ["-y", "git-commit-message-mcp"],
      "env": {
        "PROMPTS_DIR": "./.cursor/mcp/git-commit-message-mcp-prompts",
        "DEFAULT_PROMPT_FILE": "conventional",
        "MAX_DIFF_LENGTH": "3000"
      }
    }
  }
}

Supported Environment Variables:

Variable	Description	Example	Default
PROMPTS_DIR	User prompts directory	./.cursor/mcp/git-commit-message-mcp-prompts	None
DEFAULT_PROMPT_FILE	Default prompt to use	conventional, simple, detailed	default
MAX_DIFF_LENGTH	Maximum diff length	5000	3000

Note: You can also use GCM_* prefix (e.g., GCM_PROMPTS_DIR) to avoid conflicts.

Project-Level Configuration

Create .git-commit-msg.json in your project root:

{
  "promptsDir": "./.cursor/mcp/git-commit-message-mcp-prompts",
  "defaultPromptFile": "conventional",
  "maxDiffLength": 3000
}

This file can be committed to version control for team-wide sharing.

Global Configuration

Create ~/.config/git-commit-msg/config.json:

{
  "promptsDir": "~/.config/git-commit-msg/prompts",
  "defaultPromptFile": "simple"
}

Configuration Priority

1. Environment Variables (MCP config) - Highest
2. Project Config File (.git-commit-msg.json)
3. Global Config File (~/.config/git-commit-msg/config.json)
4. Built-in Defaults - Lowest

Custom Prompt Templates

Creating Custom Prompts

1. Set up prompts directory:

mkdir -p .cursor/mcp/git-commit-message-mcp-prompts

2. Create custom prompts (e.g., a.md, b.md):

# My Custom Prompt

Generate a commit message with Jira ticket.

Format: [PROJ-123] type: description

## Code Changes
Stats: {stats}
Files: {files}
Diff: {diff}

Generate commit message:

3. Configure (via MCP env or config file):

MCP Config:

{
  "env": {
    "PROMPTS_DIR": "./.cursor/mcp/git-commit-message-mcp-prompts"
  }
}

Or .git-commit-msg.json:

{
  "promptsDir": "./.cursor/mcp/git-commit-message-mcp-prompts"
}

Using Prompts in AI Chat

"Generate commit message"                    → Uses default.md
"Use conventional prompt for this commit"    → Uses conventional.md
"Use prompt a to compare featureA with main" → Uses a.md
"What prompts are available?"                → Lists all prompts

Supported Placeholders

• {diff} - Full git diff output
• {stats} - Change statistics (e.g., "3 files changed, 45 insertions(+)")
• {files} - List of changed files
• {summary} - Summary of changes

For detailed documentation, see PROMPT_SYSTEM.md.

MCP Tools

git_diff

Get git diff showing code changes.

Parameters:

• base (optional): Base branch or commit
• compare (optional): Branch or commit to compare

Examples:

// Working directory vs HEAD
git_diff()

// development vs HEAD
git_diff({ compare: "development" })

// featureA vs development
git_diff({ base: "development", compare: "featureA" })

list_prompts

List all available commit message prompts (both built-in and user-defined).

Parameters: None

Returns:

{
  "prompts": [
    { "name": "default", "source": "builtin" },
    { "name": "conventional", "source": "builtin" },
    { "name": "a", "source": "user" },
    { "name": "b", "source": "user" }
  ]
}

generate_commit_message_prompt

Generate AI prompt for commit message.

Parameters:

• diff (required): Git diff content
• stats (optional): Git diff stats
• files (optional): List of changed files
• promptName (optional): Prompt name (e.g., "conventional", "a") or file path

Examples:

// Use default prompt
generate_commit_message_prompt({ diff: "..." })

// Use specific prompt by name
generate_commit_message_prompt({ diff: "...", promptName: "conventional" })

// Use custom prompt
generate_commit_message_prompt({ diff: "...", promptName: "a" })

Examples

See the prompts/ directory for example prompt templates:

• default.md - Default prompt with Conventional Commits format
• conventional.md - Conventional Commits style (English)
• simple.md - Simple one-line style
• detailed.md - Detailed What/Why/How style

You can use these as templates for creating your own custom prompts.

For comprehensive documentation on the prompt system, see PROMPT_SYSTEM.md.

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run watch

License

MIT