Skip to main content
Glama
commit-check-mcp

commit-check-mcp

Official
by commit-check

Catch bad commits before they merge — inside your AI agent.

PyPI CI Coverage MCP Registry Glama

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-mcp

Every 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

claude mcp add commit-check -- uvx commit-check-mcp

Add --scope project to write a shareable .mcp.json at the repo root (--scope user makes it available in all your projects). You can also commit a .mcp.json containing the block above; "type": "stdio" may be added inside the server object. MCP servers are not configured in ~/.claude/settings.json.

Claude Desktop

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

Block above as-is; restart Claude Desktop.

Cursor

project .cursor/mcp.json or global ~/.cursor/mcp.json

Block above as-is (or Settings → Cursor Settings → MCP → Add new MCP server with command uvx commit-check-mcp).

VS Code (Copilot agent mode)

.vscode/mcp.json

Different key: {"servers": {"commit-check": {"type": "stdio", "command": "uvx", "args": ["commit-check-mcp"]}}}

Cline

MCP Servers panel → Configure → cline_mcp_settings.json (check your client's docs)

Block above as-is.

Roo Code

project .roo/mcp.json or global mcp_settings.json (Edit Global MCP)

Block above as-is; optional "alwaysAllow": [...].

Windsurf

~/.codeium/windsurf/mcp_config.json (check your client's docs)

Block above as-is.

Continue

config.yaml (or a file in .continue/mcpServers/)

YAML list under mcpServers:, see below. Continue also picks up the JSON block above when dropped into .continue/mcpServers/.

Zed

~/.config/zed/settings.json

Different key: {"context_servers": {"commit-check": {"command": "uvx", "args": ["commit-check-mcp"]}}}

Anything else

your client's MCP config

If the client cannot run uvx: pip install commit-check-mcp, then set "command" to the absolute path of the installed binary and drop args. Find it with which commit-check-mcp (macOS/Linux), where commit-check-mcp (Windows cmd) or Get-Command commit-check-mcp | Select-Object -ExpandProperty Source (PowerShell).

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

validate_commit_message

A commit message: Conventional Commits, subject length and case, body, sign-off, WIP and fixup markers, AI attribution

message

validate_branch_name

A branch name, or the checked-out one, and its rebase target when configured

branch?

validate_author_info

Author name and email, and whether an AI tool is the author (CC017); read from the repository's git config when omitted

author_name? author_email?

validate_commit_context

Message, branch and author in one call, for whichever you pass

message? branch? author_name? author_email?

validate_push_safety

That a push is not a force push (CC301)

push_refs? — pre-push lines; omit to compare the branch with its upstream

validate_repository_state

The latest commit's message and author, the checked-out branch and, optionally, the push

include_message include_branch include_author (default true), include_push (default false)

describe_validation_rules

Nothing: returns the merged config and the rules it enables

—

server_health

Nothing: returns the server, commit-check and MCP SDK versions

—

Every tool but server_health also takes:

  • repo_path — the repository whose cchk.toml / commit-check.toml applies. 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 from repo_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 fail is a rejection. skip means nothing was validated — never read it as approval — and warn is reported without failing the run. With commit-check 2.19.0 or later, a skipped check names why in reason, e.g. "author dependabot[bot] is in [commit].ignore_authors"; older releases leave the field out.

  • On fail, apply a non-empty fix verbatim, otherwise follow suggest, then validate again. The server's instructions teach the agent this loop.

  • A call that cannot run at all — an empty message, a repo_path that does not exist or is not a git repository where one is needed, an invalid config, a push_refs SHA 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 pytest

The 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 tools
describe_validation_rulesDescribe validation rulesA
Read-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 healthA
Read-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 infoA
Read-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 nameA
Read-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 contextA
Read-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 messageA
Read-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 safetyA
Idempotent

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 stateA
Idempotent

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

    A4.4/5.0

    Scored across 8 tools

    Disambiguation4/5

    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'.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers