Offers enhanced Git operations including repository health analysis, smart commit suggestions, detailed diff analysis, branch management, and advanced repository analytics.
Supports Jira integration through the Commitizen Jira plugin (cz_jira), enabling creation of commit messages linked to Jira tickets.
Commit Helper MCP
A Model Context Protocol (MCP) server that provides Commitizen functionality through MCP tools and resources, enabling AI assistants to generate, validate, and work with conventional commit messages.
Features
Core Functionality
Generate Commit Messages: Create conventional commit messages with validation
Validate Messages: Check existing commit messages against Commitizen rules
Interactive Questions: Get commit questions for guided message creation
Commit Types: Access available commit types and their descriptions
Configuration Access: View current Commitizen configuration and schema
Plugin Support: Works with any Commitizen plugin (conventional commits, custom plugins)
Health Monitoring: Built-in health checks and configuration refresh
🚀 Enhanced Git Integration with GitPython
Commit Helper MCP now supports GitPython for enhanced git operations:
Repository Health Analysis: Comprehensive repository metrics and scoring
Smart Commit Suggestions: AI-powered commit message suggestions based on file patterns
Detailed Diff Analysis: Line-by-line change analysis with statistics
Branch Management: Comprehensive branch and remote analysis
Performance Improvements: 2x faster operations, thread-safe execution
Advanced Git Operations: Enhanced commit previews, repository analytics, and batch operations
📦 GitPython Installation
🔄 Automatic Fallback
The system automatically selects the best available implementation:
GitPython (preferred): Enhanced features and performance
commitizen.git (fallback): Basic functionality, full compatibility
📊 Feature Comparison
Feature | Basic | Enhanced (GitPython) |
Repository status | ✅ | ✅ Rich metadata |
Commit preview | ✅ | ✅ Diff analysis |
Smart suggestions | ❌ | ✅ AI-powered |
Repository health | ❌ | ✅ Comprehensive |
Performance | Standard | 2x faster |
See GitPython Integration Guide for complete documentation.
Installation
Prerequisites
Python 3.13 or higher
uv package manager
Git repository (for Commitizen configuration detection)
Install from Source
Clone the repository:
Install dependencies:
Install the package:
Usage
MCP Inspector (Development & Testing)
Use the MCP Inspector to test and explore the server's capabilities:
This will start an interactive session where you can:
Test all available tools
Explore resources
Debug server functionality
View tool schemas and documentation
Claude Desktop Integration
To use with Claude Desktop, install the server:
This will add the server to your Claude Desktop configuration, making the tools available in your conversations.
Manual Configuration
Add to your Claude Desktop configuration file (~/Library/Application Support/Claude/claude_desktop_config.json
on macOS):
Available Tools
generate_commit_message
Generate a commit message with validation using provided parameters.
Parameters:
type
(required): Commit type (e.g., 'feat', 'fix', 'docs')subject
(required): Commit subject/descriptionbody
(optional): Detailed descriptionscope
(optional): Scope of the changebreaking
(optional): Whether this is a breaking changefooter
(optional): Footer (e.g., issue references)
Example:
create_commit_message
Generate a commit message from a complete answers dictionary.
Parameters:
answers_dict
: Dictionary containing all answers to commit questions
Example:
validate_commit_message
Validate an existing commit message against current plugin rules.
Parameters:
message
: The commit message to validate
Example:
get_commit_types
Get list of available commit types from the current plugin.
Returns: List of commit types with descriptions
get_commit_questions
Get interactive questions for commit message generation.
Returns: List of questions that can be used to build commit messages
health_check
Check the health and status of the Commitizen service.
Returns: Service health information and configuration details
refresh_configuration
Refresh the Commitizen configuration and reinitialize the service.
Returns: Status of configuration refresh
Available Resources
commitizen://config
Current Commitizen configuration including:
Active plugin information
Configuration settings
Available capabilities
Message pattern
commitizen://schema
Commit message schema showing:
Required fields
Field types and constraints
Validation rules
commitizen://example
Example commit message demonstrating the expected format for the current plugin configuration.
Configuration
The server automatically detects and uses your project's Commitizen configuration from:
pyproject.toml
(recommended).cz.toml
.cz.json
setup.cfg
Example Configuration
Add to your pyproject.toml
:
Supported Commitizen Plugins
The server works with any Commitizen plugin, including:
cz_conventional_commits (default): Standard conventional commits
cz_jira: Jira integration
cz_customize: Custom commit formats
Third-party plugins: Any plugin following Commitizen's plugin interface
Troubleshooting
Server Won't Start
Check Python version: Ensure Python 3.13+ is installed
Verify dependencies: Run
uv sync
to install dependenciesCheck Commitizen config: Ensure valid Commitizen configuration exists
View logs: Check console output for specific error messages
Invalid Commit Messages
Check plugin: Verify correct Commitizen plugin is configured
Validate config: Use
health_check
tool to verify configurationRefresh config: Use
refresh_configuration
tool after config changesCheck pattern: View
commitizen://config
resource for expected pattern
MCP Connection Issues
Verify installation: Ensure server is properly installed
Check paths: Verify file paths in Claude Desktop configuration
Test with inspector: Use
uv run mcp dev main.py
to test locallyRestart Claude: Restart Claude Desktop after configuration changes
Common Error Messages
"No Commitizen configuration found": Add Commitizen config to your project
"Plugin not found": Install the specified Commitizen plugin
"Invalid message format": Check message against plugin's expected pattern
"Service initialization failed": Check Python environment and dependencies
Development
Running Tests
Code Formatting
Local Development Server
Contributing
Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Ensure all tests pass
Submit a pull request
License
MIT License - see LICENSE file for details.
Support
For issues and questions:
Check the troubleshooting section above
Search existing issues in the repository
Create a new issue with detailed information about your problem
Changelog
See CHANGELOG.md for version history and changes.
Tools
A Model Context Protocol server that provides Commitizen functionality, enabling AI assistants to generate, validate, and work with conventional commit messages.
Related MCP Servers
- AsecurityAlicenseAqualityA Model Context Protocol server for creating commit messages from git staged files.Last updated -21MIT License
- -securityFlicense-qualityA comprehensive Model Context Protocol server implementation that enables AI assistants to interact with file systems, databases, GitHub repositories, web resources, and system tools while maintaining security and control.Last updated -331
- -securityAlicense-qualityA Model Context Protocol server that enables AI assistants to manage meeting data, including creating meeting bots, searching transcripts, and organizing calendar events.Last updated -20MIT License
- AsecurityAlicenseAqualityA flexible Model Context Protocol server that makes documentation or codebases searchable by AI assistants, allowing users to chat with code or docs by simply pointing to a git repository or folder.Last updated -12560MIT License