You can use this MCP server with Claude Code, allowing you to interact with Gerrit directly from your terminal. This repository ships as an installable Claude Code plugin.
The plugin is defined by two files in the repository root:
-
.claude-plugin/plugin.json: the plugin manifest (name and description) required by the Claude Code plugin system. -
.mcp.json: the MCP server configuration. It launches the server on-demand withuvand uses${CLAUDE_PLUGIN_ROOT}and${CLAUDE_PLUGIN_DATA}so paths resolve correctly wherever the plugin is installed:{ "mcpServers": { "gerrit": { "command": "uv", "args": ["run", "--directory", "${CLAUDE_PLUGIN_ROOT}", "gerrit-mcp-server"], "env": { "UV_PROJECT_ENVIRONMENT": "${CLAUDE_PLUGIN_DATA}/.venv" } } } }
Register the Gerrit plugin marketplace and install the plugin:
/plugin marketplace add https://gerrit.googlesource.com/gerrit-mcp-server
/plugin install gerrit@gerrit-mcp
Load the plugin locally by pointing Claude Code at the project directory:
claude --plugin-dir <path-to-gerrit-mcp-server>Because the server is launched with uv run, uv automatically creates the
environment at ${CLAUDE_PLUGIN_DATA}/.venv and installs dependencies on first
launch. There is no need to run ./build-gerrit.sh separately for the plugin.
The plugin starts the server on-demand, so no separate background process is
required. Once loaded, you can use the gerrit tools directly from claude.
Users must configure the server with the
gerrit_config.json file.
A SessionStart hook (hooks/check-config.sh, registered in
hooks/hooks.json) checks the server environment and configuration at the start
of every session, so a broken setup surfaces with clear guidance instead of MCP
tools failing silently.
The hook runs the gerrit-check-config console script, whose exit code reports
the setup state:
0: config is valid — the hook stays quiet and reports that the tools are available.1: config file is missing — the normal first-run state. The hook asks the user to run/gerrit:setup.2: config is present but invalid (bad JSON ordefault_gerrit_base_urlmismatch) — the hook asks the user to run/gerrit:setupto repair it.- any other non-zero code: the Python environment is not built. The hook offers
the exact
build-gerrit.shcommand to rebuild it.
The hook emits JSON with a systemMessage (shown to the user) and
additionalContext (telling the model what to do), because SessionStart
stdout goes to the model's context rather than the user's terminal.
skills/setup/SKILL.md provides an interactive /gerrit:setup skill that
guides the user through creating or updating the
shared user config file. The exit-code 1 and 2 states above
ask the user to run it. See
Interactive Setup in the
configuration guide for details.
skills/gerrit-workflow/SKILL.md teaches the model how to drive the git side of
Gerrit Code Review — pushing for review via refs/for/<branch>, creating new
patch sets by amending without disturbing the Change-Id trailer, working with
dependent change stacks and topics, and diagnosing common push errors such as
missing Change-Id in commit message footer or prohibited by Gerrit.
Unlike /gerrit:setup, this skill is model-invocable: Claude Code activates it
automatically whenever a task involves Gerrit git operations, so you do not need
to invoke it by name. Two reference files ship alongside it:
references/gerrit-vs-github.md— a side-by-side comparison of Gerrit and GitHub/GitLab workflows for common tasks.references/change-id-details.md— a deep dive onChange-Idcreation, squashing, cherry-picks, and edge cases.