ai-commit-helper-mcp
Reads staged Git changes from the current repository and provides tools to generate and validate commit messages according to repository-specific commit rules and length limits.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ai-commit-helper-mcp suggest three commit messages for my staged changes"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
AI Commit Helper
Three commit-message suggestions from the changes you've staged, using your repository's preferred format. Works with Codex CLI and Claude Code.
Built with TypeScript, the MCP SDK, and Zod, AI Commit Helper uses skills to guide Codex and Claude Code through generating commit messages. It supports formats like feat: add password reset and #234 Add password reset, and validates each suggestion against your repository’s format and length limit.
You choose the message. The plugin doesn't stage files, create commits, or push.
Install
You'll need Git, Node.js, npm, and either Codex CLI or Claude Code with plugin support. I used Node.js 26.6.0 and npm 11.18.0 during development.
Clone or download this repository, open a terminal in its root, and build the server.
npm ci
npm run build
npm linkThen install the plugin in your preferred tool. You can install it in both.
Codex CLI
Run these commands from the repository root.
codex plugin marketplace add .
codex plugin add ai-commit-helper@commit-helper-dev
codex plugin list --marketplace commit-helper-devClaude Code
Run these commands from the repository root.
claude plugin marketplace add ./
claude plugin install ai-commit-helper@commit-helper-dev --scope user
claude plugin listClaude Code uses the catalog in .claude-plugin/marketplace.json. Codex uses .agents/plugins/marketplace.json. Both point to plugins/ai-commit-helper and share the same skills and server.
Open a fresh session after installation. Run /mcp inside your chosen tool to check that the helper's server is connected.
This is a local installation. Keep the checkout where it is, since npm link points to the built server inside it. Installing the plugin alone doesn't build or install the server.
Related MCP server: mcp-dev-tools
Use the commit message helper
Stage the changes you want to describe, then start Codex or Claude Code.
git add README.mdAction | Codex CLI | Claude Code |
Suggest messages |
|
|
Set up repository rules |
|
|
If no rules are saved, choose the defaults or configure the repository. For ticket messages, include the ticket number in your request.
# Codex
$ai-commit-helper:commit-msg Use ticket 234.
# Claude Code
/ai-commit-helper:commit-msg Use ticket 234.Choose one of the three suggestions, review it, and commit it yourself. If interactive choices aren't available, reply with the option number. The helper stops if nothing is staged or it can't read or validate the changes.
Repository rules
Run the setup skill to choose a format and maximum title length. It creates .commit-helper.json in the repository root, even if nothing is staged. It won't overwrite an existing file.
You can also create or edit the file yourself.
{
"format": "ticket",
"maxSubjectLength": 100
}Format | Example |
|
|
|
|
Messages must be a single line. The length limit includes the prefix and spaces. Typed messages use a lowercase type with an optional scope. The validator doesn't currently support the breaking-change ! marker.
Without a file, the defaults are typed and 72. Choosing defaults doesn't save them, so the skill asks again on a later run. Use setup to save your preferences and skip that question.
Both fields are required. Invalid JSON, extra fields, unsupported formats, and length limits that aren't positive integers cause an error. Commit the configuration file if you want your team to share the same rules.
How it works
The MCP server reads the staged diff and repository rules, then validates three suggestions generated by Codex or Claude Code.
Tool | Purpose |
| Read the staged diff and active rules. |
| Check a message's format and length. |
| Save rules without overwriting existing ones. |
No separate AI API key is needed. Unstaged changes are ignored, and you should review each suggestion for accuracy.
Development
Build before running the tests. They use Node's built-in test runner and import the compiled files from build.
npm run build
node --test tests/validate.test.mjsTo try the tools directly, start MCP Inspector.
npx @modelcontextprotocol/inspector ai-commit-helper-mcpUse an absolute repository path. Subdirectory paths work too, since the server finds the repository root. Use a disposable Git repository to test configuration creation and the refusal to overwrite an existing file.
To load the plugin temporarily in Claude Code, run this from the project root.
claude --plugin-dir ./plugins/ai-commit-helperAfter changing TypeScript, rebuild and restart the agent session. Changes to installed skills or plugin configuration may also require refreshing or reinstalling the plugin.
Troubleshooting
Starting the server gives a permission error.
On macOS or Linux, run this from the checkout, then try again.
chmod u+x build/mcp.jsThe server starts but prints nothing.
That's expected when you run it alone. It communicates over stdio and waits for an MCP client such as Codex, Claude Code, or Inspector. Don't add console.log debugging to the server's stdout. Use console.error for diagnostic messages.
Suggestions describe an older version of my changes.
Check git diff --staged. Saving a file doesn't update its staged version, and generating suggestions doesn't clear the staging area.
Choice prompts don't appear.
Their availability depends on the host and session mode. The skills fall back to asking for a text reply.
License
Available Tools
3 toolscreate_commit_rulesB
Create a .commit-helper.json file in the repository root using the user's chosen commit-message rules. Fails if the file already exists.
Inputs: rules (required), repositoryPath (required).
get_commit_contextB
Get the staged Git diff and effective commit-message rules for a local repository. Returns a status of "changes" or "no_changes", the diff, and the rules to use when generating commit-message suggestions.
Inputs: repositoryPath (required).
validate_commit_messageA
Validate a proposed commit message against the target repository's configured format and maximum subject length. Returns whether the message is valid and a list of validation errors.
Inputs: message (required), repositoryPath (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool has a clearly distinct role: one retrieves context (diff + rules), one validates a message, one writes a rules file. There is no realistic overlap that would cause an agent to pick the wrong tool.
All three tools follow a strict verb_noun snake_case pattern (get_/validate_/create_ + commit-related noun). The naming is predictable and self-documenting.
Three tools is on the thin side but fits a narrowly scoped commit-message helper; each tool earns its place. No filler or redundant tools are present.
The read/validate/create surface is coherent, but create_commit_rules explicitly fails when a config already exists and there is no update or delete counterpart, leaving a real dead end for modifying rules. Agents would have to fall back to manual file editing for edits or removal.
Related MCP Connectors
Plain-English git for agents: 22 tools to branch, commit, push and tag. Free tier.
Risk-scan a diff, flag AI-generated-code tells, find secrets. 5 of 7 tools need no account.
Your coding agent asks the business logic of your repository and checks commits before they land
Read-only AI coding tools for change verification, release readiness, capacity, and guidance.
Related MCP Servers
- AlicenseBqualityBmaintenanceAutomatically generates conventional commit messages from staged git changes and checks repository status. Analyzes git diffs to create properly formatted commit messages following conventional commit standards.29MIT
- AlicenseNot gradedqualityDmaintenanceProvides AI coding assistants with tools to run git status, recent commits, tests, and linter on a real repository.ISC
- FlicenseBqualityCmaintenanceEnables Codex to delegate coding tasks to a locally hosted Qwen model through an MCP tool, which can read, write, patch, test, and inspect git diffs inside an allowed workspace.11-
- AlicenseNot gradedqualityBmaintenanceEnables Codex users to review workspace and staged files, preview diffs, stage or unstage changes, generate AI-written Chinese Conventional Commit messages from staged diffs, and switch, merge, update, and push branches from a local panel. All Git operations run through a locally registered MCP service without a cloud deployment.MIT