mcp-gerrit

An MCP (Model Context Protocol) server that gives AI assistants (Claude, Cursor, etc.) comprehensive access to your Gerrit code-review instance — 74 tools covering the full Gerrit REST API.

Tools

| Category | Tools | |---|---| | Changes | gerrit_query_changes, gerrit_get_change, gerrit_get_change_detail, gerrit_create_change, gerrit_abandon_change, gerrit_restore_change, gerrit_rebase_change, gerrit_submit_change, gerrit_cherry_pick_change, gerrit_move_change, gerrit_list_change_messages, gerrit_delete_change_message | | Reviews | gerrit_set_review (labels + inline comments + WIP) | | Reviewers | gerrit_list_reviewers, gerrit_add_reviewer, gerrit_delete_reviewer, gerrit_list_votes | | Comments | gerrit_list_change_comments, gerrit_list_revision_comments, gerrit_list_change_drafts, gerrit_create_draft, gerrit_update_draft, gerrit_delete_draft | | Revisions | gerrit_list_revision_files, gerrit_get_file_content, gerrit_get_patch, gerrit_get_related_changes, gerrit_get_mergeable, gerrit_get_revision_actions | | Projects | gerrit_list_projects, gerrit_get_project, gerrit_create_project, gerrit_delete_project, gerrit_get_project_config, gerrit_set_project_config, gerrit_get_project_head, gerrit_set_project_head, gerrit_get_project_statistics | | Branches | gerrit_list_branches, gerrit_get_branch, gerrit_create_branch, gerrit_delete_branch, gerrit_delete_branches | | Tags | gerrit_list_tags, gerrit_get_tag, gerrit_create_tag, gerrit_delete_tag, gerrit_delete_tags | | Accounts | gerrit_get_account, gerrit_query_accounts, gerrit_get_account_capabilities, gerrit_get_account_emails, gerrit_get_account_ssh_keys, gerrit_get_account_gpg_keys, gerrit_get_starred_changes, gerrit_star_change, gerrit_unstar_change | | Groups | gerrit_list_groups, gerrit_get_group, gerrit_create_group, gerrit_list_group_members, gerrit_add_group_members, gerrit_remove_group_members, gerrit_list_group_includes, gerrit_add_group_includes, gerrit_remove_group_includes | | Config | gerrit_get_server_info, gerrit_get_server_capabilities, gerrit_list_caches, gerrit_flush_cache, gerrit_flush_all_caches, gerrit_list_tasks, gerrit_kill_task, gerrit_get_summary |

Requirements

• Node.js 18 or later
• A running Gerrit instance

Installation

npm install -g @guptadevanshu/mcp-gerrit

Configuration

| Variable | Required | Description | |---|---|---| | GERRIT_URL | ✅ | Base URL of your Gerrit instance, e.g. https://gerrit.example.com | | GERRIT_USERNAME | Optional | Your Gerrit username | | GERRIT_PASSWORD | Optional | HTTP password from Settings → HTTP Credentials in Gerrit UI |

Without credentials the server uses unauthenticated access (read-only on public instances). With credentials all endpoints use the /a/ authenticated API prefix.

Use the HTTP password generated in Gerrit (not your SSO/account password). It can be revoked independently under Settings → HTTP Credentials.

Usage with Claude Desktop

Edit claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "gerrit": {
      "command": "npx",
      "args": ["-y", "@guptadevanshu/mcp-gerrit"],
      "env": {
        "GERRIT_URL": "https://gerrit.example.com",
        "GERRIT_USERNAME": "your-username",
        "GERRIT_PASSWORD": "your-http-password"
      }
    }
  }
}

Usage with Claude Code

claude mcp add gerrit \
  -e GERRIT_URL=https://gerrit.example.com \
  -e GERRIT_USERNAME=your-username \
  -e GERRIT_PASSWORD=your-http-password \
  -- mcp-gerrit

Usage with Windsurf

Edit %USERPROFILE%\.codeium\windsurf\mcp_config.json (Windows) or ~/.codeium/windsurf/mcp_config.json (macOS/Linux):

{
  "mcpServers": {
    "gerrit": {
      "command": "npx",
      "args": ["-y", "@guptadevanshu/mcp-gerrit"],
      "env": {
        "GERRIT_URL": "https://gerrit.example.com",
        "GERRIT_USERNAME": "your-username",
        "GERRIT_PASSWORD": "your-http-password"
      }
    }
  }
}

Note: Use GERRIT_URL as the env var name (not GERRIT_BASE_URL).

Usage with Cursor / other MCP clients

Point the MCP client at the mcp-gerrit binary with the same three env vars above. Any client that supports stdio MCP servers works.

Example Prompts

Show me all open changes in the platform/core project assigned to me

Review change 12345 — summarise what it does and flag any issues in the diff

Add [email protected] as a reviewer on change 12345

Vote Code-Review +2 and Verified +1 on the current patch set of change 12345

List all branches in the frontend/app project matching "release/*"

Cherry-pick change 12345 to the release/2.x branch

Create a new project called tools/my-lib with MERGE_IF_NECESSARY submit strategy

Show me which groups [email protected] belongs to

Gerrit Query Syntax

gerrit_query_changes accepts standard Gerrit query syntax:

status:open owner:self
project:my-project branch:main status:open
label:Code-Review=-1
is:reviewer status:open
age:1w status:merged
after:2024-01-01 before:2024-06-01

Development

npm install
npm run build        # compile TypeScript → dist/
npm run dev          # run directly with tsx (no build step)

Set GERRIT_URL (and optionally credentials) in your shell before running npm run dev.

License

MIT