@atef_andrus/mcp-ripgrep

An MCP server that provides ripgrep search capabilities.

Prerequisites

• ripgrep (rg) installed and available on PATH
• Node.js 22+ or Bun 1.3+

Installation

npm install @atef_andrus/mcp-ripgrep

Usage

Use as an MCP Server

Add the following to your MCP client configuration:

{
  "mcpServers": {
    "ripgrep": {
      "command": "npx",
      "args": ["@atef_andrus/mcp-ripgrep"]
    }
  }
}

Startup Options

Option	Description
--allow-dir <path>	Restrict search scope to the specified directory (can be specified multiple times)
--max-result-chars <number>	Maximum characters in results. Truncates at line boundaries when exceeded (default: 50,000)
--max-output-bytes <number>	Maximum bytes of ripgrep output. Terminates the process and truncates results when exceeded (default: 20 MB)

Configuration example with startup options:

{
  "mcpServers": {
    "ripgrep": {
      "command": "npx",
      "args": [
        "@atef_andrus/mcp-ripgrep",
        "--allow-dir", "/home/user/project",
        "--max-result-chars", "50000",
        "--max-output-bytes", "20000000"
      ]
    }
  }
}

Tools

Tool	Description
search	Pattern search with regex, literal strings, multiline matching, OR matching, context lines, and various filters. Prepends a summary of match count and file count to results
search-and-replace	Search-and-replace preview (read-only). Supports multiline matching and capture groups ($1, ${name})
search-count	Count matches per file (by line count or total matches). Supports sorting results
search-files	List files that match or do not match a pattern
list-files	List all files within the search scope
list-file-types	List file types supported by ripgrep

Key Parameters

Parameter	Description
pattern	Search pattern (regex by default)
path	Directory or file to search
fixedStrings	Treat the pattern as a literal string
caseSensitive	true = case-sensitive, false = case-insensitive, omitted = smart-case
fileType	Filter by file type (e.g., "ts", ["ts", "js"]). String or array
fileTypeNot	Exclude file types (e.g., "json", ["json", "md"]). String or array
glob	Filter by glob pattern (e.g., "*.test.ts", ["src/**", "!vendor/**"]). String or array
includeHidden	Include hidden files
followSymlinks	Follow symbolic links
maxDepth	Maximum directory traversal depth
noIgnore	Ignore .gitignore rules and search files that are normally excluded
multiline	Enable multiline matching (function signatures, import blocks, etc.)
additionalPatterns	Additional patterns for OR matching (array)
sortBy	Sort results. search / search-files / list-files: "path" "modified" "created". search-count: "path" "count" "count-asc"
maxCharacters	Maximum characters in results. Truncates at line boundaries and appends a summary when exceeded

Parameter Support by Tool

<!-- params-table-start -->

Parameter	list-file-types	list-files	search	search-and-replace	search-count	search-files
pattern	-	-	o	o	o	o
path	-	o	o	o	o	o
fixedStrings	-	-	o	o	o	o
caseSensitive	-	-	o	o	o	o
wordMatch	-	-	o	o	o	o
multiline	-	-	o	o	-	-
fileType	-	o	o	o	o	o
fileTypeNot	-	o	o	o	o	o
glob	-	o	o	o	o	o
maxResults	-	-	o	o	-	-
contextLines	-	-	o	-	-	-
beforeContext	-	-	o	-	-	-
afterContext	-	-	o	-	-	-
invertMatch	-	-	o	-	-	o
includeHidden	-	o	o	o	o	o
followSymlinks	-	o	o	o	o	o
maxDepth	-	o	o	o	o	o
additionalPatterns	-	-	o	-	-	-
jsonOutput	-	-	o	-	-	-
maxColumns	-	-	o	-	-	-
noIgnore	-	o	o	o	o	o
sortBy	-	o	o	-	o	o
maxCharacters	o	o	o	o	o	o
replacement	-	-	-	o	-	-
onlyMatching	-	-	-	o	-	-
countMode	-	-	-	-	o	-
includeZero	-	-	-	-	o	-
<!-- params-table-end -->

Development

# Install dependencies
bun install

# Run tests
bun test

# Type check
bunx tsc --noEmit

# Lint and format
bunx biome check --write .

# Build
bunx tsc

# Start in development mode
bun run dev

Security

• This server passes arguments as an array via spawn("rg", args) (no shell interpolation). Patterns and paths are placed after a -- separator to prevent flag injection.
• The --allow-dir option restricts the search scope to specified directories. Paths are resolved to absolute paths using path.resolve() and validated via prefix matching.
• Limitation: When followSymlinks is enabled, symbolic links may allow access to directories outside the allowed scope. Be aware of this when using --allow-dir together with followSymlinks.

License

MIT