@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 | - |

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