commit-check-mcp
OfficialCommit-check-mcp is an MCP server that lets an AI agent validate commit-related metadata against Commit Check policy rules before committing or pushing.
Validate commit messages for Conventional Commits format, subject length/case, body, sign-off, WIP/fixup markers, and AI attribution.
Validate branch names and configured merge-base requirements.
Validate author name/email and whether an AI tool is the author, reading git config when values are omitted.
Validate message, branch, and author together in one call.
Check push safety to detect force pushes, using pre-push refs or upstream comparison.
Validate the current repository state: HEAD commit message, author, checked-out branch, and optional push safety.
Describe the effective merged config and enabled validation rules.
Report server, commit-check, and MCP SDK versions.
Accept repo_path, config_path, and inline config overrides; return structured pass/fail/skip results with rule IDs, errors, suggestions, fixes, and docs links.
Allows Codeium's Windsurf IDE to validate commit messages, branch names, author info, push safety, and repository state using commit-check.
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., "@commit-check-mcp validate commit message 'fix: typo' in current repository"
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.
Catch bad commits before they merge — inside your AI agent.
Docs · Rules · CLI · GitHub Action · GitHub App
The Model Context Protocol server for Commit Check, commit policy as code for teams and AI agents. It gives your coding agent the rules your CI enforces: the agent validates its commit message, branch name and author before it commits or pushes, and when a correction is unambiguous it gets the fix to apply.
Quick start
claude mcp add commit-check -- uvx commit-check-mcpEvery other client launches the same command. This is the object to register:
{
"mcpServers": {
"commit-check": {
"command": "uvx",
"args": ["commit-check-mcp"]
}
}
}No uv yet? curl -LsSf https://astral.sh/uv/install.sh | sh — or use
pip install commit-check-mcp, as in the last row below.
Where each client keeps it
Client | Where it goes | Notes |
Claude Code |
| Add |
Claude Desktop | macOS | Block above as-is; restart Claude Desktop. |
Cursor | project | Block above as-is (or Settings → Cursor Settings → MCP → Add new MCP server with command |
VS Code (Copilot agent mode) |
| Different key: |
Cline | MCP Servers panel → Configure → | Block above as-is. |
Roo Code | project | Block above as-is; optional |
Windsurf |
| Block above as-is. |
Continue |
| YAML list under |
Zed |
| Different key: |
Anything else | your client's MCP config | If the client cannot run |
Continue's config.yaml entry in full (name, version and schema are required by Continue; drop them if you are adding only the mcpServers fragment to an existing file, or save this as a standalone file in .continue/mcpServers/):
name: commit-check
version: 0.0.1
schema: v1
mcpServers:
- name: commit-check
command: uvx
args: ["commit-check-mcp"]Related MCP server: mcp-commits
Tools
Tool | What it checks | Arguments |
| A commit message: Conventional Commits, subject length and case, body, sign-off, WIP and fixup markers, AI attribution |
|
| A branch name, or the checked-out one, and its rebase target when configured |
|
| Author name and email, and whether an AI tool is the author (CC017); read from the repository's git config when omitted |
|
| Message, branch and author in one call, for whichever you pass |
|
| That a push is not a force push (CC301) |
|
| The latest commit's message and author, the checked-out branch and, optionally, the push |
|
| Nothing: returns the merged config and the rules it enables | — |
| Nothing: returns the server, commit-check and MCP SDK versions | — |
Every tool but server_health also takes:
repo_path— the repository whosecchk.toml/commit-check.tomlapplies. It must be a git repository when the tool reads git state; a plain directory holding a config file is enough when you pass every value yourself.config_path— a config file to use instead of the repository's own; relative paths resolve fromrepo_path.config— inline overrides merged on top, e.g.{"commit": {"require_body": true}}.
No tool changes the working tree or the commits. validate_push_safety and
validate_repository_state may run git fetch to resolve a SHA, so only they
are annotated as not read-only; a client that gates on MCP tool hints can
auto-approve the other six.
Validate a message with the repository's rules:
{
"message": "feat(api): add MCP validation tool",
"repo_path": "/path/to/repo"
}Check the repository as it stands, including the push:
{
"repo_path": "/path/to/repo",
"include_push": true
}Validate push safety from git pre-push ref metadata (<local_ref> <local_sha> <remote_ref> <remote_sha>):
{
"repo_path": "/path/to/repo",
"push_refs": "refs/heads/main abc123 refs/heads/main def456"
}See which rules apply once an override is merged in:
{
"repo_path": "/path/to/repo",
"config": {
"commit": {
"require_body": true
}
}
}Results
Every validate_* tool returns the shape commit-check --format json prints:
{
"status": "pass|fail|skip",
"warnings": 0,
"checks": [
{
"rule_id": "CC001",
"check": "message",
"status": "pass|fail|warn|skip",
"value": "...",
"error": "...",
"suggest": "...",
"fix": "...",
"docs_url": "https://commit-check.com/rules/#cc001",
"reason": ""
}
]
}Only
failis a rejection.skipmeans nothing was validated — never read it as approval — andwarnis reported without failing the run. With commit-check 2.19.0 or later, a skipped check names why inreason, e.g."author dependabot[bot] is in [commit].ignore_authors"; older releases leave the field out.On
fail, apply a non-emptyfixverbatim, otherwise followsuggest, then validate again. The server's instructions teach the agent this loop.A call that cannot run at all — an empty
message, arepo_paththat does not exist or is not a git repository where one is needed, an invalid config, apush_refsSHA that cannot be resolved — comes back as an MCP tool error that names the problem, never as a pass.
Development
pip install -e .[dev]
python -m pytestThe server speaks stdio, so an MCP client launches it; run uvx commit-check-mcp
by hand only to see that it starts.
Community
Questions and ideas go to Discussions, bugs to Issues. Releases follow Semantic Versioning. Released under the MIT License.
mcp-name: io.github.commit-check/commit-check-mcp
Available Tools
8 toolsdescribe_validation_rulesDescribe validation rulesARead-onlyIdempotent
Return the commit-check rules that are in effect after merging the built-in defaults, the repository's config file (or config_path) and the inline config overrides. Read-only, no side effects.
Returns {commit_check_version, config (the merged config), supported_checks (every check name commit-check knows), enabled_rules[]} where each enabled rule carries its check name, config and pattern details.
Use this before writing a commit message or branch name to learn the expected format instead of guessing, and to debug why a validation failed or was skipped.
Inputs: config, repo_path, config_path. Returns: object
server_healthServer healthARead-onlyIdempotent
Return server and dependency versions. Read-only, no side effects.
Returns {server, server_version, commit_check_version, mcp_sdk_version}. Useful as a first call to verify the server is running and to check version compatibility.
Inputs: no named parameters. Returns: object
validate_author_infoValidate author infoARead-onlyIdempotent
Validate a commit author's name and/or email against the configured rules (e.g. allowed email domains, name patterns, and under ai_attribution forbid/disclose that the author is not an AI tool). Read-only.
Returns {status, warnings, checks[]}. status is 'pass', 'fail' or 'skip': only 'fail' is a rejection; 'skip' means every check skipped, so nothing was validated and the result is not approval. warnings is the number of checks with status 'warn'. Each check has: rule_id (stable rule id, e.g. 'CC001'); check (rule name, e.g. 'message'); status 'pass' | 'fail' | 'warn' | 'skip' ('warn' = the config lists the check under warn, so the finding is reported without failing the run; 'skip' = the rule did not run, e.g. the author is in ignore_authors or there was nothing to check); value (what was checked); error (why it failed); suggest (advice for a person); fix (the corrected value when the correction is unambiguous, else ''); docs_url (documentation for the rule). On 'fail', apply a non-empty fix verbatim; when fix is '', rewrite following suggest; then validate again.
Use this to check author metadata before committing. Only the values you pass are checked; if neither is given, both are read from repo_path's git config (falling back to the latest commit) and repo_path must be a git repository. For combined validation use validate_commit_context.
Inputs: config, repo_path, author_name, config_path, +1 more. Returns: object
validate_branch_nameValidate branch nameARead-onlyIdempotent
Validate a branch name against the configured naming convention (e.g. feature/, bugfix/) and, when configured, that the branch is based on the required merge base. Read-only.
Returns {status, warnings, checks[]}. status is 'pass', 'fail' or 'skip': only 'fail' is a rejection; 'skip' means every check skipped, so nothing was validated and the result is not approval. warnings is the number of checks with status 'warn'. Each check has: rule_id (stable rule id, e.g. 'CC001'); check (rule name, e.g. 'message'); status 'pass' | 'fail' | 'warn' | 'skip' ('warn' = the config lists the check under warn, so the finding is reported without failing the run; 'skip' = the rule did not run, e.g. the author is in ignore_authors or there was nothing to check); value (what was checked); error (why it failed); suggest (advice for a person); fix (the corrected value when the correction is unambiguous, else ''); docs_url (documentation for the rule). On 'fail', apply a non-empty fix verbatim; when fix is '', rewrite following suggest; then validate again.
Use this before creating or pushing a branch. Omit branch to check the branch currently checked out in repo_path. For combined message+branch+author validation use validate_commit_context.
Inputs: branch, config, repo_path, config_path. Returns: object
validate_commit_contextValidate commit contextARead-onlyIdempotent
Run the commit message, branch name and author checks together in one call, for whichever of message, branch, author_name and author_email you pass. Read-only.
Returns {status, warnings, checks[]}. status is 'pass', 'fail' or 'skip': only 'fail' is a rejection; 'skip' means every check skipped, so nothing was validated and the result is not approval. warnings is the number of checks with status 'warn'. Each check has: rule_id (stable rule id, e.g. 'CC001'); check (rule name, e.g. 'message'); status 'pass' | 'fail' | 'warn' | 'skip' ('warn' = the config lists the check under warn, so the finding is reported without failing the run; 'skip' = the rule did not run, e.g. the author is in ignore_authors or there was nothing to check); value (what was checked); error (why it failed); suggest (advice for a person); fix (the corrected value when the correction is unambiguous, else ''); docs_url (documentation for the rule). On 'fail', apply a non-empty fix verbatim; when fix is '', rewrite following suggest; then validate again.
Use this to validate several aspects of a commit you are about to make with a single call. At least one of message, branch, author_name or author_email is required; omitted aspects are not checked. For one aspect use validate_commit_message, validate_branch_name or validate_author_info; for the commit already at HEAD use validate_repository_state.
Inputs: branch, config, message, repo_path, +3 more. Returns: object
validate_commit_messageValidate commit messageARead-onlyIdempotent
Validate a commit message against commit-check rules (Conventional Commits type and format, subject length and case, body, sign-off, WIP/fixup markers, AI attribution: whatever the effective config enables). Read-only; touches no git state.
Returns {status, warnings, checks[]}. status is 'pass', 'fail' or 'skip': only 'fail' is a rejection; 'skip' means every check skipped, so nothing was validated and the result is not approval. warnings is the number of checks with status 'warn'. Each check has: rule_id (stable rule id, e.g. 'CC001'); check (rule name, e.g. 'message'); status 'pass' | 'fail' | 'warn' | 'skip' ('warn' = the config lists the check under warn, so the finding is reported without failing the run; 'skip' = the rule did not run, e.g. the author is in ignore_authors or there was nothing to check); value (what was checked); error (why it failed); suggest (advice for a person); fix (the corrected value when the correction is unambiguous, else ''); docs_url (documentation for the rule). On 'fail', apply a non-empty fix verbatim; when fix is '', rewrite following suggest; then validate again.
Use this when you have one commit message string to check before committing. To check message, branch and author in one call use validate_commit_context; to check the latest commit already in a repository use validate_repository_state.
Inputs: message (required), config, repo_path, config_path. Returns: object
validate_push_safetyValidate push safetyAIdempotent
Check that a pending push is not a force push (rule CC301, no_force_push): fails when a
remote_sha is not an ancestor of its local_sha, i.e. the push would rewrite remote history.
Leaves your working tree and commits untouched, but may run git fetch <remote> <ref> to
resolve SHAs, which updates FETCH_HEAD and remote-tracking refs. A SHA that cannot be resolved
even then is a tool error, never a pass. Force pushes are always rejected by this tool;
push.allow_force_push in config cannot re-enable them here.
Returns {status, warnings, checks[]}. status is 'pass', 'fail' or 'skip': only 'fail' is a rejection; 'skip' means every check skipped, so nothing was validated and the result is not approval. warnings is the number of checks with status 'warn'. Each check has: rule_id (stable rule id, e.g. 'CC001'); check (rule name, e.g. 'message'); status 'pass' | 'fail' | 'warn' | 'skip' ('warn' = the config lists the check under warn, so the finding is reported without failing the run; 'skip' = the rule did not run, e.g. the author is in ignore_authors or there was nothing to check); value (what was checked); error (why it failed); suggest (advice for a person); fix (the corrected value when the correction is unambiguous, else ''); docs_url (documentation for the rule). On 'fail', apply a non-empty fix verbatim; when fix is '', rewrite following suggest; then validate again.
Call this before git push. Only the no_force_push rule runs. When it fails there is no
automatic fix (fix is ''): follow suggest, i.e. push without --force/--force-with-lease or
rebase onto the remote first, then validate again.
Inputs: config, push_refs, repo_path, config_path. Returns: object
validate_repository_stateValidate repository stateAIdempotent
Validate what is already in a local git repository: the latest commit's message and author,
the checked-out branch name and, optionally, whether pushing that branch to its upstream would
be a force push. Leaves the working tree and commits untouched; the push check may run
git fetch, which updates FETCH_HEAD and remote-tracking refs.
Returns {status, warnings, checks[]}. status is 'pass', 'fail' or 'skip': only 'fail' is a rejection; 'skip' means every check skipped, so nothing was validated and the result is not approval. warnings is the number of checks with status 'warn'. Each check has: rule_id (stable rule id, e.g. 'CC001'); check (rule name, e.g. 'message'); status 'pass' | 'fail' | 'warn' | 'skip' ('warn' = the config lists the check under warn, so the finding is reported without failing the run; 'skip' = the rule did not run, e.g. the author is in ignore_authors or there was nothing to check); value (what was checked); error (why it failed); suggest (advice for a person); fix (the corrected value when the correction is unambiguous, else ''); docs_url (documentation for the rule). On 'fail', apply a non-empty fix verbatim; when fix is '', rewrite following suggest; then validate again.
Use this to check a repository's current state in one call, e.g. after committing and before pushing, or in a hook. The include_* flags select the checks; at least one must be true. To validate values that are not yet committed use validate_commit_context or the single-aspect tools.
Inputs: config, repo_path, config_path, include_push, +3 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a distinct validation aspect (author, branch, message, push, repo state) and descriptions explicitly cross-reference when to prefer the aggregate validate_commit_context or validate_repository_state. The only real overlap is validate_commit_context duplicating the three single-aspect validators, which is intentional but still leaves an agent a choice point between 'one aspect' and 'aggregate'.
The set follows a clear verb_noun pattern (validate_*, describe_*) with consistent snake_case throughout. The lone deviation is server_health, which is a noun phrase with no verb, though it is a conventional health-check name.
Eight tools is well-scoped for a commit-rule validation server: one discovery tool, five validators covering each aspect plus an aggregate and repo-state check, one push-safety tool, and a health probe. No tool appears redundant beyond the deliberately layered aggregate/single validators.
The surface covers the full pre-commit lifecycle: inspect effective rules, validate message/branch/author individually or together, validate an existing HEAD commit, and check push safety. A minor gap is validating arbitrary historical commits or commit ranges, since validate_repository_state only inspects the latest commit at HEAD.
Maintenance
Related MCP Connectors
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
Zero-log MCP server with 49 tools for AI guardrails, secret scanning, MCP linting & EU compliance.
Free MCP tools: the only MCP linter, health checks, cost estimation, and trust evaluation.
The MCP server that vets MCP servers: identity, risk grade and per-tool risk before you install.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables automated code review and GitHub PR commenting through MCP integration.1,032 npm9MIT
- FlicenseNot gradedqualityDmaintenanceMCP server providing commit rules with SemVer and conventional commits format for development teams.-
- FlicenseNot gradedqualityDmaintenanceEnables dependency, security, and coding convention checks for Python and Java projects via MCP tools. Supports local paths or Git URLs.-
- FlicenseNot gradedqualityDmaintenanceEnables AI clients to inspect Git repository changes, run allowlisted validation commands, and generate Markdown review reports via MCP, with validation disabled by default for security.-