commit-check-mcp

Model Context Protocol (MCP) server for commit-check.

commit-check-mcp exposes commit-check as local MCP tools so an MCP client can validate commit messages, branch names, author info, push safety, and repository state.

Features

This MCP server exposes commit-check validations as MCP tools:

• server_health — returns server/sdk versions

• validate_commit_message — validates a commit message

• validate_branch_name — validates a branch name or the current repo branch

• validate_push_safety — validates that a push is not a force push

• validate_author_info — validates author name/email or the repo's git author config

• validate_commit_context — runs combined checks in one call

• validate_repository_state — validates latest commit, current branch, author state, and optional push safety for a repo

• describe_validation_rules — returns the effective config and enabled rules after merging defaults and repo config

All validation tools return the same structured commit-check result shape:

{
  "status": "pass|fail",
  "checks": [
    {
      "check": "message",
      "status": "pass|fail",
      "value": "...",
      "error": "...",
      "suggest": "..."
    }
  ]
}

Related MCP server: code-review-mcp-server

Installation

pip install commit-check-mcp

This installs the commit-check-mcp CLI entrypoint.

For local development from this repository:

pip install -e .

Use With An MCP Client

This server runs over stdio, so it is meant to be launched by an MCP client rather than used as a long-running HTTP service.

With uvx (recommended — no install needed):

# Run once, no pip install required
uvx commit-check-mcp

Tip: If uv is not installed, get it via curl -LsSf https://astral.sh/uv/install.sh | sh.

Claude Desktop

{
  "mcpServers": {
    "commit-check": {
      "command": "uvx",
      "args": ["commit-check-mcp"]
    }
  }
}

Claude Code CLI

{
  "mcpServers": {
    "commit-check": {
      "command": "uvx",
      "args": ["commit-check-mcp"]
    }
  }
}

Add to your ~/.claude/settings.json or project-level .claude/settings.local.json.

Cursor

In Cursor, go to Settings → Cursor Settings → MCP → Add new MCP server and paste:

Or add to your project's .cursor/mcp.json:

{
  "mcpServers": {
    "commit-check": {
      "command": "uvx",
      "args": ["commit-check-mcp"]
    }
  }
}

Windsurf

Add to your ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "commit-check": {
      "command": "uvx",
      "args": ["commit-check-mcp"]
    }
  }
}

Cline (VS Code)

Add a new MCP server in the Cline extension settings:

{
  "mcpServers": {
    "commit-check": {
      "command": "uvx",
      "args": ["commit-check-mcp"]
    }
  }
}

Continue.dev (VS Code / JetBrains)

Add to your ~/.continue/config.json:

{
  "experimental": {
    "mcpServers": {
      "commit-check": {
        "command": "uvx",
        "args": ["commit-check-mcp"]
      }
    }
  }
}

Roo Code

Add to your Roo Code MCP settings:

{
  "mcpServers": {
    "commit-check": {
      "command": "uvx",
      "args": ["commit-check-mcp"]
    }
  }
}

Zed

Add to your ~/.config/zed/settings.json:

{
  "mcp_servers": {
    "commit-check": {
      "command": "uvx",
      "args": ["commit-check-mcp"]
    }
  }
}

Generic / Any MCP Client

If your client does not support uvx, use pip and the direct path:

pip install commit-check-mcp
which commit-check-mcp

Then use the absolute path in your config:

{
  "mcpServers": {
    "commit-check": {
      "command": "/path/to/commit-check-mcp"
    }
  }
}

Run Manually

# If installed via pip
commit-check-mcp

# Or via uvx (no install needed)
uvx commit-check-mcp

The server uses stdio transport, which is the recommended MCP default for local tool integrations.

Tool Usage

After the client starts the server, it will expose these tools:

• server_health: returns server, SDK, and dependency versions

• validate_commit_message(message, config?, repo_path?, config_path?)

• validate_branch_name(branch?, config?, repo_path?, config_path?)

• validate_push_safety(push_refs?, config?, repo_path?, config_path?)

• validate_author_info(author_name?, author_email?, config?, repo_path?, config_path?)

• validate_commit_context(message?, branch?, author_name?, author_email?, config?, repo_path?, config_path?)

• validate_repository_state(repo_path?, config?, config_path?, include_message?, include_branch?, include_author?, include_push?)

• describe_validation_rules(config?, repo_path?, config_path?)

The common optional arguments are:

• repo_path: repository directory to validate against

• config_path: explicit TOML config file; relative paths resolve from repo_path

• config: ad-hoc config overrides merged on top of defaults and repo config

Common Examples

Validate a commit message using repo-local rules:

{
  "message": "feat(api): add MCP validation tool",
  "repo_path": "/path/to/repo"
}

Validate the current repository branch using an explicit config file:

{
  "repo_path": "/path/to/repo",
  "config_path": ".github/commit-check.toml"
}

Validate the full repository state:

{
  "repo_path": "/path/to/repo",
  "include_message": true,
  "include_branch": true,
  "include_author": true
}

Validate push safety from git pre-push hook ref metadata:

{
  "repo_path": "/path/to/repo",
  "push_refs": "refs/heads/main abc123 refs/heads/main def456"
}

Inspect the final merged rules that will be applied:

{
  "repo_path": "/path/to/repo",
  "config": {
    "commit": {
      "require_body": true
    }
  }
}

Repository-Aware Validation

commit-check is most useful when it runs against a real git repository and its cchk.toml or commit-check.toml file. This MCP server now supports that directly:

• repo_path — run git-based validations against a specific repository

• config_path — point to an explicit TOML config file; relative paths are resolved from repo_path

• config — apply ad-hoc overrides on top of defaults and repo config

Typical patterns:

• Validate an explicit message with a repository's rules

• Validate the current repository state without passing message/branch/author values manually

• Validate push safety using pre-push ref metadata, or check the current branch against its upstream

• Inspect which rules are actually enabled after config merging

Example payload for a repository-wide validation:

{
  "repo_path": "/path/to/repo",
  "include_message": true,
  "include_branch": true,
  "include_author": true,
  "include_push": true
}

Config precedence is:

1. commit-check built-in defaults

2. repository config loaded from repo_path

3. config_path when explicitly provided

4. inline config overrides passed to the tool

Published On

mcp-name: io.github.commit-check/commit-check-mcp