Skip to main content
Glama
Chromium CodeSearch MCP

Chromium CodeSearch MCP

by hjanuschka

Chromium Helper Logo

Chromium Helper

npm version npm downloads License: MIT GitHub stars

The ultimate toolkit for exploring Chromium and PDFium source code
CLI tool & MCP server for code search, Gerrit integration, and issue tracking

Features • Quick Start • Documentation • Contributing • License

📋 Table of Contents

🎯 Features

Why Use Chromium Helper?

  • 🚀 Zero Friction - Start searching immediately with npx, no setup required

  • 📊 Real-time Data - Direct access to Google's official APIs, same as source.chromium.org

  • 🔍 Smart Search - Full Google CodeSearch syntax with regex, filters, and more

  • 🤖 AI-Ready - JSON output and MCP integration for automation

  • 📱 Cross-Platform - Works on macOS, Linux, and Windows

What Can You Do?

Feature

Description

Example

Code Search

Search 20M+ lines with advanced syntax

Find all LOG(INFO) calls

Symbol Lookup

Find definitions and usages

Locate Browser::Create

Gerrit Review

Check CLs, comments, diffs, try-bots, errors

Review CL 6624568

Issue Tracking

Search and analyze bugs

Find memory leak issues

PDFium Support

Full PDFium code and reviews

Check PDFium CL 130850

Commit History

Search by message, author, date

Find recent security fixes

Code Ownership

Find OWNERS and reviewers

Who owns chrome/browser?

Two Ways to Use

  1. 🔧 CLI Tool (chromium-helper) - Direct terminal access with ch commands

  2. 🤖 MCP Server (chromium-codesearch-mcp) - AI integration for Claude Desktop

💡 Why CLI First?

As Armin Ronacher points out, a well-designed CLI is often superior to context-cluttering MCPs. Our CLI works seamlessly with ANY AI coding assistant:

Claude, Cursor, Gemini, or any AI: Just ask them to run:

npx chromium-helper --ai

This dumps comprehensive documentation that the AI can use to help you explore Chromium's codebase without any special configuration or context pollution.

Example AI Prompt:

"Run npx chromium-helper --ai to learn the tool, then help me find all WebRTC-related memory leaks in Chromium"

The AI will:

  1. Execute the command to understand all capabilities

  2. Use appropriate search commands with filters

  3. Analyze results and provide insights

  4. All without cluttering your AI's context window!

Real Example in Action:

AI Assistant using chromium-helper

In this example, the AI assistant:

  • First runs npx ch --ai to learn the tool

  • Checks CL 6624568 for test status (✅ all 30/30 bots passed)

  • Retrieves review comments with proper formatting

  • Provides a comprehensive summary of the CL status and reviewer feedback

  • All in a clean, organized output!


🚀 Quick Start

CLI Tool - Use Instantly!

# No installation needed - just use npx!
npx chromium-helper search "LOG(INFO)" --limit 5
npx chromium-helper gerrit bots 6624568
npx chromium-helper --ai  # Show comprehensive AI guide

# Or install globally for the short 'ch' alias
npm install -g chromium-helper
ch search "WebContents" --type class
ch gerrit status 6624568 --format json
ch pdfium bots 130850 --failed-only

🤖 Using with AI Coding Assistants (Claude Code, Cursor, Gemini, etc.)

Simply tell your AI assistant:

Run: npx chromium-helper --ai
Then help me [your task here]

Example tasks:

  • "Find all uses of base::RefCounted in the codebase"

  • "Check if CL 6624568 has passing tests and show me the review comments"

  • "Search for recent security fixes in the renderer"

  • "Find who owns the password manager code"

  • "Help me understand what PDFium CL 130850 does"

  • "Show me all failing bots for a specific CL"

MCP Server - For AI Integration

# Add to Claude Desktop (see configuration below)
npm install -g chromium-codesearch-mcp

# Or test directly
echo '{"query": "LOG(INFO)", "limit": 3}' | npx chromium-codesearch-mcp search_chromium_code

📖 Documentation

CLI Tool Documentation

  • Quick Help: Run ch --help for command overview

  • AI Guide: Run ch --ai for comprehensive usage guide with examples

  • Full Documentation: See CLI README

Example Commands

# Code search
ch search "CreateWindow" --type function --limit 10
ch symbol Browser::Create
ch file "base/logging.cc" --lines 100-200

# Gerrit operations
ch gerrit status 6624568
ch gerrit comments 6624568 --unresolved-only
ch gerrit diff 6624568 --file "chrome/browser/ui/browser.cc"
ch gerrit bots 6624568 --failed-only
ch gerrit bot-errors 6624568  # Get detailed error messages with stack traces
ch gerrit bot-errors 6624568 --bot linux  # Filter to specific bot

# Gerrit list (requires authentication)
ch auth login  # One-time browser-based authentication
ch gerrit list --query "status:open owner:me"
ch pdfium list --query "status:open"

# Issue tracking
ch issues search "memory leak" --limit 20
ch issues get 422768753

# PDFium
ch pdfium status 130850
ch pdfium diff 130850
ch pdfium bots 130850

# Commit history & ownership
ch commits "password manager" --author "chrome-team" --since "2025-06-01"
ch owners "chrome/browser/ui/browser.cc"

🔧 CLI Tool Usage

The CLI provides comprehensive access to Chromium's codebase with intuitive commands.

Global Options

  • --format <json|table|plain> - Output format (default: plain)

  • --debug - Enable debug logging

  • --no-color - Disable colored output

  • --ai - Show comprehensive AI usage guide

Key Commands

Command

Description

Example

search

Search code with Google syntax

ch search "LOG(INFO)" --limit 5

symbol

Find symbol definitions

ch symbol Browser::Create

file

Get file content

ch file "base/logging.h" --start 100 --end 200

auth

Authentication management

ch auth login

gerrit

Gerrit CL operations

ch gerrit bot-errors 6624568

pdfium

PDFium Gerrit operations

ch pdfium status 130850

issues

Search/view issues

ch issues search "memory leak"

commits

Search commit history

ch commits "fix" --author "chrome-team"

owners

Find OWNERS files

ch owners "chrome/browser/ui/"

🔐 Authentication for Gerrit Lists

The gerrit list and pdfium list commands require authentication. We've made this super easy!

# One-time setup - interactive cookie setup (recommended)
ch auth manual

# Alternative: automated browser login (may be blocked by Google)
ch auth login

# Check if you're authenticated
ch auth status

# Now use gerrit commands without any cookies!
ch gerrit list
ch pdfium list --query "status:open owner:me"

# Clear saved authentication
ch auth logout

Manual Cookie Option: If you prefer manual setup:

ch auth help  # Shows how to extract cookies manually
ch gerrit list --auth-cookie "SID=...; __Secure-1PSID=..."

Output Formats

# Human-readable (default)
ch search "WebContents"

# JSON for scripts/AI
ch search "WebContents" --format json | jq '.[] | .file'

# Table format
ch gerrit bots 6624568 --format table

🤖 MCP Server Usage

The MCP server enables AI assistants like Claude to search and analyze Chromium code.

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "chromium-codesearch": {
      "command": "npx",
      "args": ["chromium-codesearch-mcp"]
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "chromium-codesearch": {
      "command": "chromium-codesearch-mcp"
    }
  }
}

Available MCP Tools

Core Search & Navigation

  • search_chromium_code - Advanced code search with filtering options

  • find_chromium_symbol - Symbol definitions and usage examples

  • get_chromium_file - File content with line number ranges

Chromium Gerrit Integration

  • get_gerrit_cl_status - CL status, test results, submit requirements

  • get_gerrit_cl_comments - Review comments with code context

  • get_gerrit_cl_diff - Code changes and file modifications

  • get_gerrit_patchset_file - File content from specific patchsets

  • get_gerrit_cl_bot_errors - Detailed error messages with stack traces from failed try-bots

  • get_ci_build_errors - Detailed error messages from specific CI builds

  • list_gerrit_cls - List Gerrit CLs with authentication (requires cookies)

PDFium Gerrit Integration

  • get_pdfium_gerrit_cl_status - PDFium CL status and test results

  • get_pdfium_gerrit_cl_comments - PDFium review comments

  • get_pdfium_gerrit_cl_diff - PDFium code changes

  • get_pdfium_gerrit_patchset_file - PDFium file content from patchsets

  • list_pdfium_gerrit_cls - List PDFium Gerrit CLs with authentication (requires cookies)

Issue Tracking & History

  • get_chromium_issue - Detailed issue information with browser automation

  • search_chromium_issues - Search issues with full-text and pagination

  • search_chromium_commits - Commit history search with date filtering

  • find_chromium_owners_file - Code ownership and reviewer discovery

Example MCP Prompts

Ask Claude to:

  • "Search for LOG(INFO) usage in Chromium"

  • "Find the definition of Browser::Create"

  • "Check the status of Gerrit CL 6624568"

  • "Search for memory leak issues"

  • "Get the diff for PDFium CL 130850"

  • "List my open Gerrit CLs" (requires providing authentication cookie)


📦 Installation

CLI Tool

# Option 1: Use without installation (recommended)
npx chromium-helper <command>

# Option 2: Install globally for 'ch' shortcut
npm install -g chromium-helper

MCP Server

# Option 1: Use with npx in Claude config (recommended)
# Add to claude_desktop_config.json as shown above

# Option 2: Install globally
npm install -g chromium-codesearch-mcp

From Source

git clone https://github.com/hjanuschka/chromium-helper.git
cd chromium-helper

# For CLI
cd chromium-helper-cli
npm install && npm run build
npm link  # Optional: make globally available

# For MCP Server
cd ../
npm install && npm run build

🔧 Development

Prerequisites

  • Node.js 18+

  • TypeScript

  • npm or yarn

Development Commands

# Install dependencies
npm install

# Build both packages
npm run build

# Watch mode (CLI)
cd chromium-helper-cli && npm run dev

# Test MCP server
npm test

# Run locally
node dist/index.js

Project Structure

chromium-helper/
├── chromium-helper-cli/    # CLI tool package
│   ├── src/               # TypeScript source
│   ├── dist/              # Compiled output
│   └── package.json
├── src/                   # MCP server source
├── dist/                  # MCP compiled output
├── package.json           # MCP server package
└── README.md             # This file

🤝 Contributing

We welcome contributions! Here's how you can help:

Reporting Issues

  • Check existing issues first

  • Include reproduction steps

  • Mention your OS and Node version

Submitting PRs

  1. Fork the repository

  2. Create a feature branch (git checkout -b feature/amazing-feature)

  3. Commit your changes (git commit -m 'Add amazing feature')

  4. Push to the branch (git push origin feature/amazing-feature)

  5. Open a Pull Request

Code Style

  • Use TypeScript

  • Follow existing patterns

  • Add tests for new features

  • Update documentation

Ideas for Contributions

  • Add more search filters

  • Improve error messages

  • Add new output formats

  • Enhance PDFium support

  • Add more MCP tools

📊 Technical Details

API Usage

  • Chromium CodeSearch: https://grimoireoss-pa.clients6.google.com

  • Gerrit API: https://chromium-review.googlesource.com

  • Issue Tracker: https://issues.chromium.org

Performance

  • Caches API responses

  • Parallel request support

  • Efficient pagination

  • Minimal dependencies

❓ FAQ

Q: Do I need to install anything to use this?

No! Just use npx chromium-helper <command> to run instantly.

Q: What's the difference between the CLI and MCP server?

  • CLI: Direct terminal usage for developers

  • MCP: Integration with AI assistants like Claude

Q: Can I search PDFium code too?

Yes! Full PDFium support for code search and Gerrit operations.

Q: Is this official Google software?

No, but it uses Google's official public APIs that power source.chromium.org.

Q: How do I see all available commands?

Run ch --ai for a comprehensive guide, or ch --help for a quick overview.

Q: Can I use this in scripts?

Yes! Use --format json for machine-readable output.

Q: What API key do I need?

None required! It uses the public API by default.

📄 License

MIT License - see LICENSE for details.

🌟 Acknowledgments

  • Google Chromium team for the amazing CodeSearch API

  • PDFium team for their great documentation

  • MCP protocol team at Anthropic

  • All contributors and users


Made with ❤️ for the Chromium community

NPM (CLI) • NPM (MCP) • Report Issues • Star on GitHub

Available Tools

23 tools
find_chromium_owners_fileC

Find OWNERS files for a given file path in Chromium source code by searching up the directory tree

Inputs: file_path (required).

find_chromium_symbolC

Find symbol definition, references, and usage in Chromium source

Inputs: symbol (required), file_path.

get_chromium_fileC

Get contents of a specific file from Chromium source

Inputs: file_path (required), line_start, line_end.

get_chromium_issueC

Get details for a specific Chromium issue/bug from issues.chromium.org

Inputs: issue_id (required).

get_ci_build_errorsA

Get detailed error messages with stack traces from a specific CI build URL. This provides the actual test failures, assertion errors, and complete stack traces from a CI build.

Inputs: build_url (required).

get_gerrit_cl_bot_errorsA

Get detailed error messages with stack traces from failed try-bots for a Chromium Gerrit CL. This includes the actual test failures, assertion errors, and full stack traces to diagnose why tests failed.

Inputs: cl_number (required), patchset, bot_filter, failed_only.

get_gerrit_cl_commentsC

Get review comments for a Chromium Gerrit CL patchset

Inputs: cl_number (required), patchset, include_resolved.

get_gerrit_cl_diffB

Get the diff/changes for a Chromium Gerrit CL patchset to understand what code was modified

Inputs: cl_number (required), patchset, file_path.

get_gerrit_cl_statusC

Get status and test results for a Chromium Gerrit CL

Inputs: cl_number (required).

get_gerrit_cl_trybot_statusA

Get detailed try-bot status for a Chromium Gerrit CL, including individual bot results and pass/fail counts

Inputs: cl_number (required), patchset, failed_only.

get_gerrit_patchset_fileB

Get the content of a specific file from a Gerrit patchset for making code changes

Inputs: cl_number (required), file_path (required), patchset.

get_pdfium_gerrit_cl_commentsB

Get review comments for a PDFium Gerrit CL patchset

Inputs: cl_number (required), patchset, include_resolved.

get_pdfium_gerrit_cl_diffB

Get the diff/changes for a PDFium Gerrit CL patchset to understand what code was modified

Inputs: cl_number (required), patchset, file_path.

get_pdfium_gerrit_cl_statusC

Get status and test results for a PDFium Gerrit CL

Inputs: cl_number (required).

get_pdfium_gerrit_cl_trybot_statusA

Get detailed try-bot status for a PDFium Gerrit CL, including individual bot results and pass/fail counts

Inputs: cl_number (required), patchset, failed_only.

get_pdfium_gerrit_patchset_fileC

Get the content of a specific file from a PDFium Gerrit patchset for making code changes

Inputs: cl_number (required), file_path (required), patchset.

list_chromium_folderB

List files and folders in a specific directory of the Chromium source tree

Inputs: folder_path (required).

list_gerrit_clsB

List Gerrit CLs from Chromium dashboard (requires authentication cookie)

Inputs: auth_cookie (required), query, limit.

list_pdfium_gerrit_clsA

List PDFium Gerrit CLs from PDFium dashboard (requires authentication cookie)

Inputs: auth_cookie (required), query, limit.

search_chromium_codeC

Search for code in the Chromium source repository using Google's official Code Search syntax

Inputs: query (required), case_sensitive, language, file_pattern, +3 more.

search_chromium_commitsC

Search commit messages and metadata in the Chromium repository using Gitiles API

Inputs: query (required), author, since, until, +1 more.

search_chromium_issuesB

Search for issues in the Chromium issue tracker with full-text search across titles, descriptions, and metadata

Inputs: query (required), limit, start_index.

suggest_reviewers_for_clA

Find optimal reviewers for a Chromium CL. Analyzes OWNERS files and recent commit activity to suggest the minimal set of reviewers who can cover all changed files. Ranks reviewers by both OWNERS coverage and recent commit activity.

Inputs: cl_number (required), patchset, max_reviewers, fast, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 23 tools

    Disambiguation4/5

    Most tools have distinct purposes targeting different resources (e.g., Chromium vs. PDFium, file operations vs. issue tracking vs. CI builds). However, there is some overlap between Chromium and PDFium Gerrit tools (e.g., get_gerrit_cl_comments vs. get_pdfium_gerrit_cl_comments) that could cause confusion if the domain isn't clearly specified in queries. The descriptions help differentiate, but the parallel structures create minor ambiguity.

    Naming Consistency5/5

    Tool names follow a highly consistent verb_noun pattern with clear prefixes (e.g., get_, list_, search_, find_). All tools use snake_case uniformly, and the naming conventions are predictable across the set, making it easy to understand each tool's function at a glance.

    Tool Count3/5

    With 23 tools, the count feels heavy for a code search server, though it covers multiple domains (Chromium source, Gerrit, PDFium, CI). It's borderline because the scope is broad but not excessive; however, the duplication between Chromium and PDFium tools inflates the count without adding unique functionality, making it slightly over-scoped.

    Completeness5/5

    The tool set provides comprehensive coverage for Chromium development workflows, including code search, file access, issue tracking, Gerrit CL management (status, diffs, comments), CI error analysis, and reviewer suggestions. There are no obvious gaps; it supports full lifecycle operations from code exploration to patch review and debugging.

    Related MCP Connectors