Searchfox MCP Server
A comprehensive Model Context Protocol (MCP) server that provides full access to Mozilla's Searchfox code search and analysis service. This server enables AI assistants to search through Mozilla codebases, analyze code structure, retrieve file contents, and understand call relationships.
[!WARNING] Prefer using searchfox-cli for agentic workflows (like Claude Code) instead of this MCP.
Features
- Advanced Code Search: Unified search with advanced query syntax (symbol:, id:, path:, etc.)
- Symbol Analysis: Search for symbols and extract complete definitions
- Call Graph Analysis: Analyze function call relationships with three query modes
- Memory Layout: View C++ class/struct memory layout with field offsets
- Git Blame: Get commit history for specific lines or files
- File Operations: Retrieve file contents with line range support
- Path Search: Find files matching specific patterns
- Multiple Repositories: Support for mozilla-central, autoland, mozilla-beta, ESR branches, and more
Available Tools (8 Total)
1. search
Unified code search with advanced query syntax and filtering capabilities.
Parameters:
query(string): Search query with optional advanced syntaxsymbol:Name- Symbol search (definitions/declarations)id:Name- Exact identifier matchingpath:dir/file- Path filterpathre:regex- Path regex filtertext:exact- Exact text searchre:pattern- Regular expression pattern
repo(string, optional): Repository to search in (default: "mozilla-central")case_sensitive(boolean, optional): Enable case sensitive searchlimit(number, optional): Maximum number of results (default: 50)context_lines(number, optional): Number of context lines before/after matchesfilters(object, optional): Additional filterslanguage: Filter by language (cpp, c, js, webidl, rust)exclude_tests: Exclude test filesexclude_generated: Exclude generated filesexclude_thirdparty: Exclude third-party filesonly_tests: Include only test files
Example:
{
"query": "symbol:AudioContext path:dom/media",
"filters": {
"language": "cpp",
"exclude_tests": true
}
}
2. get_file
Retrieve file contents with optional line range support.
Parameters:
path(string): File path within the repositoryrepo(string, optional): Repository name (default: "mozilla-central")lines(object, optional): Line range to retrievestart(number): Starting line number (1-based)end(number): Ending line number (inclusive)context(number): Additional context lines before/after range
Example:
{
"path": "dom/media/AudioContext.cpp",
"lines": {
"start": 100,
"end": 200,
"context": 5
}
}
3. search_paths
Find files by path pattern.
Parameters:
pattern(string): File path pattern to search forrepo(string, optional): Repository to search in (default: "mozilla-central")limit(number, optional): Maximum number of results (default: 100)
Example:
{
"pattern": "AudioContext",
"repo": "mozilla-central"
}
4. search_symbols
Dedicated symbol/identifier search with language and path filtering.
Parameters:
symbol(string): Symbol or identifier name to search fortype(string, optional): Search type - "symbol" (default) or "identifier"repo(string, optional): Repository to search in (default: "mozilla-central")path_filter(string, optional): Path filter to narrow resultslimit(number, optional): Maximum number of results (default: 50)language(string, optional): Filter by language (cpp, c, js, webidl, rust)
Example:
{
"symbol": "MediaStream",
"type": "symbol",
"path_filter": "dom/media",
"language": "cpp"
}
5. get_definition
Extract complete function/class definitions using intelligent brace-matching.
Parameters:
symbol(string): Symbol name to get definition forrepo(string, optional): Repository to search in (default: "mozilla-central")path_filter(string, optional): Path filter to find the right definitionlanguage(string, optional): Language hint - cpp, c, js, webidl, rust, or "auto" (default: "auto")max_lines(number, optional): Maximum number of lines to extract (default: 500)
Features:
- Intelligent brace-matching state machine
- Handles nested braces, strings, comments, escape sequences
- Supports C++, C, Rust, JavaScript, and WebIDL
- Scans backward to find function/class start
- Includes initializer lists in C++
Example:
{
"symbol": "AudioContext",
"path_filter": "dom/media",
"language": "cpp"
}
6. get_call_graph
Analyze function call relationships with three query modes.
Parameters:
mode(string): Query modecalls-from- What does this function call?calls-to- What calls this function?calls-between- Find call paths between two functions
source_symbol(string): Source symbol/function nametarget_symbol(string, optional): Target symbol (required for calls-between mode)repo(string, optional): Repository to search in (default: "mozilla-central")depth(number, optional): Maximum traversal depth 1-3 (default: 1)
Features:
- Results grouped by class/namespace
- Overloaded functions collapsed together
- Formatted markdown output
- Depth control for breadth-first traversal
Language Support:
- ✅ C++ (full support)
- ✅ Java, Kotlin, Python (via SCIP indexing)
- ❌ JavaScript/TypeScript (not supported)
Example:
{
"mode": "calls-from",
"source_symbol": "mozilla::dom::AudioContext::Create",
"depth": 2
}
7. get_field_layout
Get C++ class/struct memory layout information.
Parameters:
class_name(string): C++ class or struct namerepo(string, optional): Repository to search in (default: "mozilla-central")
Features:
- Shows size and alignment in bytes
- Lists base classes with offsets
- Shows field offsets, sizes, and types
- Handles template class variants
- C++ only
Example:
{
"class_name": "mozilla::dom::AudioContext",
"repo": "mozilla-central"
}
8. get_blame
Get git blame information for files.
Parameters:
path(string): File path within the repositoryrepo(string, optional): Repository to search in (default: "mozilla-central")start_line(number, optional): Starting line number (default: 1)end_line(number, optional): Ending line number (inclusive)
Features:
- Shows commit hash, author, date, and message
- Supports line range filtering
- Batches commit info requests for efficiency
- Formatted markdown output
Example:
{
"path": "dom/media/AudioContext.cpp",
"start_line": 100,
"end_line": 200
}
Supported Repositories
mozilla-central(default) - Main development branchautoland- Integration branchmozilla-beta- Beta release branchmozilla-release- Release branchmozilla-esr115,mozilla-esr128,mozilla-esr140- ESR branchescomm-central- Thunderbird codebase
Installation
# Clone the repository
git clone https://github.com/canova/searchfox-mcp.git
cd searchfox-mcp
# Install dependencies
npm install
# Build the project
npm run build
Usage
Claude Desktop Configuration
Add to your claude_desktop_config.json:
{
"mcpServers": {
"searchfox": {
"command": "node",
"args": ["/absolute/path/to/searchfox-mcp/dist/index.js"]
}
}
}
Configuration file locations:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
Other MCP Clients
This server uses stdio transport and follows the MCP protocol specification. Configure your MCP client to run:
node /path/to/searchfox-mcp/dist/index.js
Query Syntax Examples
Basic Searches
// Simple text search
{"query": "AudioContext"}
// Symbol search
{"query": "symbol:MediaStream"}
// Exact identifier
{"query": "id:nsISupports"}
// Path filtered search
{"query": "AudioNode path:dom/media/webaudio"}
// Regular expression
{"query": "re:Create.*Context"}
Advanced Filtering
// C++ code only, exclude tests
{
"query": "symbol:AudioContext",
"filters": {
"language": "cpp",
"exclude_tests": true,
"exclude_generated": true
}
}
// JavaScript in tests only
{
"query": "AudioContext",
"filters": {
"language": "js",
"only_tests": true
}
}
Workflow Examples
Understanding a New API:
- Search for symbol:
{"query": "symbol:AudioContext"} - Get definition:
{"symbol": "AudioContext", "language": "cpp"} - See what it calls:
{"mode": "calls-from", "source_symbol": "mozilla::dom::AudioContext::Create"} - Find usage:
{"mode": "calls-to", "source_symbol": "mozilla::dom::AudioContext::Create"}
Debugging a Crash:
- Get implementation:
{"symbol": "MediaStream::AddTrack"} - See what it calls:
{"mode": "calls-from", "source_symbol": "mozilla::dom::MediaStream::AddTrack"} - Check blame:
{"path": "dom/media/MediaStream.cpp", "start_line": 100, "end_line": 150}
Memory Layout Analysis:
- Get layout:
{"class_name": "mozilla::dom::AudioContext"} - Check field sizes and offsets for padding analysis
- Understand inheritance hierarchy
Development
# Install dependencies
npm install
# Build the project
npm run build
# Run in development mode with hot reload
npm run dev
# Linting
npm run lint
npm run lint:fix
# Formatting
npm run format
npm run format:check
Architecture
This MCP server is built with a modular architecture:
src/
├── index.ts # Main server, tool registration
├── types.ts # TypeScript interfaces
├── constants.ts # Constants and mappings
├── tools/ # Tool implementations
│ ├── search.ts # Unified search
│ ├── files.ts # File operations
│ ├── symbols.ts # Symbol tools
│ ├── callgraph.ts # Call graph analysis
│ ├── analysis.ts # Field layout
│ └── blame.ts # Git blame
├── parsers/ # Code parsing utilities
│ ├── definition-extractor.ts # Brace-matching parser
│ └── callgraph-parser.ts # Call graph parsing
└── utils/ # Shared utilities
├── searchfox-client.ts # Searchfox API client
├── github-client.ts # GitHub API client
├── repo-mapping.ts # Repository mappings
├── query-builder.ts # Query syntax parsing
└── filters.ts # Filtering utilities
Related Projects
- searchfox-cli - Command-line tool for Searchfox (Rust)
- Searchfox - Mozilla's code search website
License
Licensed under either of
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.