MCP 服务器

@atef_andrus/mcp-ripgrep

An MCP server that wraps ripgrep to provide powerful text search, search-and-replace, file listing, and file type listing capabilities within a defined scope.

README

@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

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.