Skip to main content
Glama
Gerrit MCP Server

Gerrit MCP Server

Official
README.md
# 🐍 Gerrit MCP Server

An MCP (Model Context Protocol) server that brings Gerrit code-review workflows
to AI clients including the Gemini CLI, Claude Code, and OpenAI Codex. It
provides tools to search changes, inspect diffs and review metadata, manage
reviewers, comments, and change state, and analyze related or dependent changes.
Optional extensions add tools backed by Gerrit plugins.

Use it as a **Gemini CLI extension**, **Claude Code plugin**, or **Codex
plugin**, or run it directly as a persistent **HTTP server** or on-demand via
**STDIO**.

## 📚 Documentation

For detailed information, please see the documents in the `docs/` directory:

- **[Configuration](docs/configuration.md)**: A detailed guide to the
  `gerrit_config.json` file and all authentication methods.
- **[Testing Guide](docs/testing.md)**: Instructions on how to run the unit,
  integration, and E2E tests.
- **[Gemini CLI Setup](docs/gemini-cli.md)**: How to configure the Gemini CLI to
  use this server.
- **[Claude Code Setup](docs/claude-code.md)**: How to use this server as a
  Claude Code plugin.
- **[Codex Setup](docs/codex.md)**: How to use this server as a Codex plugin.
- **[Best Practices](docs/best_practices.md)**: Tips for using the server
  effectively.
- **[Contributing](docs/contributing.md)**: Guidelines for contributing to the
  project.
- **[Available Tools](docs/available_tools.md)**: A list of all available tools
  and their descriptions.
- **[Extensions](docs/extensions.md)**: How to register additional MCP tools
  without modifying the core server.
- **[Example Use Cases](docs/use_cases.md)**: Scenarios demonstrating how to use
  the server.

## Reporting bugs and feature requests

Please report bugs and feature requests in the
[Gerrit MCP Server component](https://issues.gerritcodereview.com/components/1895778)
of the [Gerrit issue tracker](https://issues.gerritcodereview.com/).

Due to spam abuse, membership in the
[repo-discuss Google Group](https://groups.google.com/group/repo-discuss) is
required to create issues. See the
[announcement](https://www.gerritcodereview.com/2025-06-05-community-managers-minutes.html#reducing-spam-on-both-issue-tracker-and-gerritgooglesource)
for more information.

## 🚀 Getting Started

### 1. Prerequisites

Before you begin, ensure you have the following tools installed and available in
your system's `PATH`.

- **Python 3.12+**: Required by the server.
- **[uv](https://docs.astral.sh/uv/getting-started/installation/)**: Used for
  dependency management and running the server. Optional — the build script will
  install it via `pip` if absent.
- **curl**: The standard command-line tool for transferring data with URLs.

### 2. Build the Environment

Run the build script from the root of the `gerrit-mcp-server` project directory.
This will create a virtual environment in `.venv` via `uv sync` and install all
dependencies.

```bash
./build-gerrit.sh
```

### 3. Configure the Server

Create the shared user config file described in the
**[Configuration Guide](docs/configuration.md)**. Copy the sample to the default
location (using the project virtual environment's Python):

```bash
config_path=$(uv run python -c 'from platformdirs import user_config_path; print(user_config_path("gerrit-mcp") / "gerrit_config.json")')
mkdir -p "$(dirname "$config_path")"
cp gerrit_mcp_server/gerrit_config.sample.json "$config_path"
```

Customize it for your environment. `GERRIT_CONFIG_PATH` overrides the default.
Existing repo-local configs must be moved or explicitly selected with that
variable; they are not migrated automatically.

Alternatively, if your harness supports skills (tested with Claude Code), the
`/gerrit:setup` skill can create or repair this file for you interactively. See
**[Interactive Setup](docs/configuration.md#interactive-setup-gerritsetup)**.

### 4. Run the Server (HTTP Mode)

To run the server as a persistent background process, use the `server.sh`
script:

- **Start the server:**
  ```bash
  ./server.sh start
  ```
- **Check the status:**
  ```bash
  ./server.sh status
  ```
- **Stop the server:**
  ```bash
  ./server.sh stop
  ```

For on-demand STDIO mode or client-specific installation instructions, see the
**[Gemini CLI Setup Guide](docs/gemini-cli.md)**,
**[Claude Code Setup Guide](docs/claude-code.md)**, or
**[Codex Setup Guide](docs/codex.md)**.

## Contributing

To contribute code or other changes, use the canonical
[gerrit-mcp-server repository](https://gerrit.googlesource.com/gerrit-mcp-server)
hosted on Gerrit and follow the [contribution guidelines](docs/contributing.md).
This project does not accept GitHub pull requests.

## Security

This is not an officially supported Google product. This project is not eligible
for the
[Google Open Source Software Vulnerability Rewards Program](https://bughunters.google.com/open-source-security).

TDQS

B3/5.0

Scored across 25 tools

Disambiguation4/5

Most tools target distinct actions and resources, but there is minor overlap between query_changes and query_changes_by_date_and_filters, and between delete_draft_comments (all) and delete_draft_comment (single). The descriptions clarify these boundaries, so an agent can generally select correctly.

Naming Consistency4/5

The overwhelming majority follow a verb_noun pattern (query_, get_, list_, delete_, set_, create_, etc.). The notable exception is 'changes_submitted_together', which is a noun phrase rather than a verb-first name, and 'query_changes_by_date_and_filters' is longer but still verb-initial.

Tool Count3/5

With 25 tools, the server sits at the high end of what is typically considered heavy. While each tool has a specific purpose for Gerrit operations, the count is borderline and may feel bloated compared to more focused servers.

Completeness4/5

The server covers the core Gerrit lifecycle well: create, query, get details, modify state, comment, add reviewers, revert, and abandon. However, it lacks a direct 'submit' operation, which is a notable gap for a Gerrit client, and also misses actions like restoring an abandoned change or editing a commit message.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues