The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Gerrit Code Review listing page.
An MCP (Model Context Protocol) server that exposes Gerrit code review operations as capability-gated tools. An AI agent can search and read changes, publish review comments, vote, and drive change-state transitions. Every write capability is an explicit operator opt-in.
Two defaults encode it:
read group only. Write capability never appears unless enabled via --groups.--own-changes-only=false.An agent leaving unwanted trail on colleagues' changes is an externally visible failure; a missing capability is a locally discoverable inconvenience. The defaults are chosen accordingly. Widen deliberately:
Binary release: download the binary for your platform from
GitHub Releases, make it executable, and put it on
your PATH:
Docker:
go install:
The server reads connection identity from environment variables only; credentials never travel through flags:
| Variable | Meaning |
|---|---|
GERRIT_URL | Base URL of the Gerrit instance |
GERRIT_USERNAME | Account username for HTTP Basic authentication |
GERRIT_TOKEN | HTTP credential paired with the username |
Generate the credential in Gerrit under Settings → HTTP Credentials (an HTTP password, or an auth token on instances that issue them). All three variables are required; the server exits with an error naming the missing ones.
Everything the server needs is read from the environment: the identity variables above plus a GERRIT_MCP_* mirror
for every flag (see Configuration reference). MCP server processes inherit the session
environment, so in Claude Code one user-level registration turns into per-project configuration, down to different
Gerrit instances with different credentials per repository.
~/.claude.json holds the registration, with no env block:
<project>/.claude/settings.local.json carries the project's environment; every env entry reaches the server
process:
Values shared by most projects can sit one layer down in ~/.claude/settings.json. Settings files merge, with
.claude/settings.local.json over .claude/settings.json over ~/.claude/settings.json, so a project declares only
its deltas. Anything no layer sets falls back to the server's own defaults: read-only, own changes.
The registration's env block stays empty for a reason. A variable named there shadows every settings layer, and
references are no workaround: ${VAR} expands only from the shell environment that launched claude, never from
settings files, and anything unresolved reaches the server as a literal string.
Other MCP clients inherit their launch environment the same way, so per-directory tooling such as direnv achieves the identical split without client support.
Capability is selected at startup via --groups as a comma-separated list. Groups are independent and combinable,
with no privilege ladder: each write-capable group bundles the minimal change-read subset it needs to work on its
own, and enabled groups union.
| Group | Tools |
|---|---|
read | search_changes, get_change, list_change_files, get_file_diff, get_change_comments |
comment | get_change, get_change_comments, post_comments |
transition | get_change, set_vote, transition_change |
search_changes: query changes with Gerrit's change query syntax, paginated.get_change: one change in review-relevant detail: status, owner, labels with votes, current revision, messages.list_change_files: files touched by a revision, with per-file change stats.get_file_diff: the diff of one file in a revision.get_change_comments: comment threads on a change, with resolution state and comment ids. Returns unresolved
threads only by default; status=all fetches the full history, status=resolved the settled threads.post_comments: publish a review in one call: optional top-level message plus inline, range, file-level, and
reply comments. Replies anchor to comment ids from get_change_comments; resolved toggles the thread state.set_vote: set a label vote (e.g. Code-Review) with an optional message; value 0 clears an own vote.transition_change: move a change's state: submit, abandon, restore, wip, or ready, with an optional
message (submit accepts none). Gerrit's refusal (a blocked submit, a restore of a merged change) is reported
verbatim.An opt-in push channel for review activity. The agent subscribes to a change with subscribe_change; from then on,
new change messages, votes, inline comment threads, and status transitions arrive in the session on their own as
review_activity blocks. The payload uses the same llmxml vocabulary the read tools emit and carries the activity
whole, so nothing needs fetching afterwards. unsubscribe_change ends a subscription early. A merged or abandoned
change ends its own subscription with a final notification that says so, and a change that becomes unreadable
(deleted, or no longer visible to the account) does the same, with the reason spelled out.
Subscriptions are per-session and in-memory: they leave no trace on the Gerrit instance, end with the session, and after a server restart the agent subscribes again. With the feature off (the default) the server is byte-identical to its pre-feature self, with no extra tools or capabilities and no background polling.
Enabling takes both sides:
--review-notifications=true (or its mirror). The server registers both subscription tools
and polls Gerrit every --review-notifications-poll-interval (default 60s): one batched query per tick over
all subscribed changes, with detail fetches only for changes that actually moved.mcpServers, launch with
claude --dangerously-load-development-channels server:<name>, where <name> is the registration key; it
becomes the source attribute of the injected <channel> blocks. Allowlisted channel plugins load with
claude --channels instead.Research-preview caveats: organization policy can disable channels entirely; the flag syntax may change between Claude Code releases; and a client without channel support silently drops the events, in which case the server behaves exactly as if the feature were off, with no errors on either side.
Noise control is operator configuration. The server applies no heuristics of its own and filters nothing by message tag, because a bot's verdict is often exactly the outcome the agent is waiting for:
--review-notifications-include-own keeps it);--review-notifications-exclude-accounts silences accounts by username or numeric ID;--review-notifications-exclude-patterns drops events whose message or comment text matches a regular
expression; an invalid pattern fails startup with an error naming it.Every flag has a GERRIT_MCP_* mirror that follows the same settings layering as the rest of the configuration
(see Per-project configuration), so a project can enable notifications
and pick exclusions in its own settings file.
Behavior is configured by CLI flags, each mirrored by an environment variable so one configuration style works for binary and Docker invocations alike. Precedence: the flag wins over its mirror, and the mirror wins over the default.
| Flag | Mirror | Default | Meaning |
|---|---|---|---|
--groups | GERRIT_MCP_GROUPS | read | Comma-separated capability groups: read, comment, transition |
--projects | GERRIT_MCP_PROJECTS | (empty) | Project allowlist confining every operation, reads included |
--own-changes-only | GERRIT_MCP_OWN_CHANGES_ONLY | true | Refuse trail-leaving operations on changes not owned by the authenticated account |
--include-tools | GERRIT_MCP_INCLUDE_TOOLS | (empty) | Keep only the listed tools from the group-resolved set |
--exclude-tools | GERRIT_MCP_EXCLUDE_TOOLS | (empty) | Remove the listed tools from the group-resolved set |
--review-notifications | GERRIT_MCP_REVIEW_NOTIFICATIONS | false | Enable review notifications |
--review-notifications-poll-interval | GERRIT_MCP_REVIEW_NOTIFICATIONS_POLL_INTERVAL | 60s | Poll cadence for subscribed changes, as a Go duration |
--review-notifications-include-own | GERRIT_MCP_REVIEW_NOTIFICATIONS_INCLUDE_OWN | false | Keep the authenticated account's own activity in notifications |
--review-notifications-exclude-accounts | GERRIT_MCP_REVIEW_NOTIFICATIONS_EXCLUDE_ACCOUNTS | (empty) | Accounts (usernames or numeric IDs) whose activity never becomes a notification |
--review-notifications-exclude-patterns | GERRIT_MCP_REVIEW_NOTIFICATIONS_EXCLUDE_PATTERNS | (empty) | Comma-separated regular expressions; matching message or comment text never becomes a notification |
Notes:
--own-changes-only takes an explicit boolean value: --own-changes-only=false. A bare flag without a value is a
configuration error.--projects) is enforced server-side: a project clause is injected into every change query
regardless of what the agent composed, and direct operations on out-of-scope changes are refused.--exclude-tools removes tools from what the groups resolved; --include-tools keeps
only the listed subset of it. A tool outside the enabled groups can never be activated by a filter, and exclude
wins over include. Filter entries naming no known tool fail startup, so misconfigurations surface immediately.Every tool responds in llmxml, an LLM-digestible subset of XML: line-structured, semantically tagged text meant to be read by a model. Attributes carry metadata; element bodies carry content:
There is no XML declaration, no namespaces, and no schema; nothing parses it back. If you need machine-readable Gerrit data, use Gerrit's REST API directly; this format is for model consumption.