Skip to main content
Glama
AtefAndrus

@atef_andrus/mcp-ripgrep

by AtefAndrus
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

@atef_andrus/mcp-ripgrep

npm version CI License: MIT

An MCP server that provides ripgrep search capabilities.

Prerequisites

  • ripgrep (rg) installed and available on PATH

  • Node.js 22+ or Bun 1.3+

Related MCP server: ripgrep-mcp

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

Available Tools

6 tools
list-filesRipgrep List FilesA

List all files in the search scope using ripgrep. No pattern matching — just lists files that would be searched.

ParametersJSON Schema
NameRequiredDescriptionDefault
globNoGlob pattern to filter files
pathYesDirectory to list files from
sortByNoSort results by field
fileTypeNoFilter by file type (e.g. 'ts', 'py')
maxDepthNoMaximum directory traversal depth
noIgnoreNoDo NOT respect .gitignore rules (search files that are normally ignored)
fileTypeNotNoExclude file type
includeHiddenNoInclude hidden files and directories
maxCharactersNoMaximum characters in the result. Truncated with summary if exceeded.
followSymlinksNoFollow symbolic links

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden. It discloses that the tool uses ripgrep and performs no pattern matching, which is useful behavior beyond the schema, but it omits read-only safety, default ignore behavior, symlink behavior, and output truncation details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tightly written sentences with no filler. The purpose is front-loaded, and the 'No pattern matching' clarification directly follows to prevent misuse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple listing tool with no output schema, the description sufficiently indicates what is returned ('lists files') and how it differs from searching. The rich input schema covers parameters, though default behavioral details like ignore rules and truncation are left to schema parameter descriptions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, so all ten parameters are already documented there. The description does not add parameter-level meaning beyond the schema's baseline, which is appropriate for a high-coverage schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List all files') with scope ('in the search scope') and implementation context ('using ripgrep'). The phrase 'No pattern matching' clearly distinguishes it from the sibling search tools that match content or patterns.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives a clear usage condition: use this when you want files without pattern matching. It implies the alternative (search tools) but does not explicitly name when-not or the sibling alternatives such as search or search-files.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list-file-typesRipgrep List File TypesA

List all file types supported by ripgrep. Useful for finding valid values for the fileType parameter.

ParametersJSON Schema
NameRequiredDescriptionDefault
maxCharactersNoMaximum characters in the result. Truncated with summary if exceeded.

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden. 'List' truthfully implies a read-only operation, and no contradiction exists, but it says nothing about return format, ordering, or the truncation behavior implied only by the schema's maxCharacters. Adequate but thin for an annotation-free tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, zero filler, with the tool's output front-loaded and its purpose following immediately. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a trivial read-only listing tool with no output schema and full schema param coverage, the description supplies enough to call it correctly: what it returns and why. Only a note about output shape would improve it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

One parameter with 100% schema description coverage, so the schema already documents maxCharacters and its truncation behavior. The description adds no parameter-level detail beyond what the schema provides, matching the baseline 3 for high-coverage schemas.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource: 'List all file types supported by ripgrep.' An agent can immediately tell this is a metadata-enumeration tool rather than a search tool, distinguishing it from the search*/list-files siblings. It stops short of naming a sibling explicitly, so it stays at 4 rather than 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear context: 'Useful for finding valid values for the fileType parameter.' This tells the agent exactly when the tool is wanted (populating a fileType argument). It does not name alternatives or state when not to use it, so it falls short of the 5 bar.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search-and-replaceRipgrep Search and Replace PreviewA

Read-only preview of search-and-replace results using ripgrep. Does NOT modify files. Useful for previewing replacements and testing capture groups ($1, $2, ${name}).

ParametersJSON Schema
NameRequiredDescriptionDefault
globNoGlob pattern to filter files
pathYesDirectory or file to search
patternYesSearch pattern (regex by default)
fileTypeNoFilter by file type (e.g. 'ts', 'py')
maxDepthNoMaximum directory traversal depth
noIgnoreNoDo NOT respect .gitignore rules (search files that are normally ignored)
multilineNoEnable multiline matching (for function signatures, import blocks, etc.)
wordMatchNoOnly match whole words
maxResultsNoMaximum matches per file
fileTypeNotNoExclude file type (e.g. 'json')
replacementYesReplacement string (supports $1, $2, ${name} for capture groups)
fixedStringsNoTreat pattern as a literal string
onlyMatchingNoShow only the matched/replaced text instead of the full line (useful for extracting captured groups)
caseSensitiveNotrue = case-sensitive, false = case-insensitive, omit = smart-case
includeHiddenNoInclude hidden files and directories
maxCharactersNoMaximum characters in the result. Truncated with summary if exceeded.
followSymlinksNoFollow symbolic links

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the safety burden and does well by declaring the operation is read-only and does not modify files, plus mentions capture group substitution semantics. It omits any note on result truncation/limits or output shape, though maxCharacters is documented in the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences with the most important constraint (read-only, no modification) front-loaded. No filler or restatement of the tool name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 17-parameter tool with no annotations and no output schema, the description is quite thin — it doesn't explain what the preview output looks like, how matches are reported, or how truncation surfaces. The rich schema compensates somewhat, so it is adequate but not complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so every parameter is already documented, giving a baseline of 3. The description echoes capture-group syntax ($1, $2, ${name}) that is already present in the replacement parameter description, adding no meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('search-and-replace results using ripgrep') and immediately narrows scope with 'Read-only preview' and 'Does NOT modify files'. An agent can distinguish it from the sibling 'search' tool, which presumably only finds matches without replacement.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear when-to-use context ('previewing replacements and testing capture groups'). However, it never names an alternative tool or states when NOT to use it (e.g., 'use search if you only need to find matches'), so routing guidance is implicit rather than explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search-countRipgrep Search CountB

Count pattern matches per file using ripgrep. Returns file paths with their match counts.

ParametersJSON Schema
NameRequiredDescriptionDefault
globNoGlob pattern to filter files
pathYesDirectory or file to search
sortByNoSort results: 'path' (alphabetical), 'count' (descending), 'count-asc' (ascending)
patternYesSearch pattern (regex by default)
fileTypeNoFilter by file type (e.g. 'ts', 'py')
maxDepthNoMaximum directory traversal depth
noIgnoreNoDo NOT respect .gitignore rules (search files that are normally ignored)
countModeNo'lines' counts matching lines (default), 'matches' counts all matches including multiple per line
wordMatchNoOnly match whole words
fileTypeNotNoExclude file type
includeZeroNoInclude files with zero matches in the output
fixedStringsNoTreat pattern as a literal string
caseSensitiveNotrue = case-sensitive, false = case-insensitive, omit = smart-case
includeHiddenNoInclude hidden files and directories
maxCharactersNoMaximum characters in the result. Truncated with summary if exceeded.
followSymlinksNoFollow symbolic links

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It usefully discloses the return format (paths + counts), but says nothing about read-only safety, truncation behavior (despite a maxCharacters param), or performance characteristics of a recursive ripgrep count.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero waste, and the core action plus return value are front-loaded. Nothing needs trimming.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 16-parameter tool with no annotations and no output schema, the description covers purpose and return shape adequately, and the rich schema compensates for parameter details. Only the absence of usage routing and truncation/pagination notes keeps it from being fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all 16 parameters in detail. The description adds no syntax, default, or interaction details beyond that, which is the baseline 3 when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('count pattern matches per file using ripgrep') and even describes the return shape (file paths with match counts). It implicitly separates itself from the sibling 'search' (which presumably returns matches rather than counts), but it never explicitly names an alternative.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use, when-not-to-use, or alternative-tool guidance at all. An agent must infer from the sibling names ('search', 'search-files') whether counting is preferable to listing matches.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search-filesRipgrep Search FilesA

List files that match (or do not match) a pattern using ripgrep. Returns file paths only, no line content.

ParametersJSON Schema
NameRequiredDescriptionDefault
globNoGlob pattern to filter files
pathYesDirectory or file to search
sortByNoSort results by field
patternYesSearch pattern (regex by default)
fileTypeNoFilter by file type (e.g. 'ts', 'py')
maxDepthNoMaximum directory traversal depth
noIgnoreNoDo NOT respect .gitignore rules (search files that are normally ignored)
wordMatchNoOnly match whole words
fileTypeNotNoExclude file type
invertMatchNoIf true, list files that do NOT contain the pattern
fixedStringsNoTreat pattern as a literal string
caseSensitiveNotrue = case-sensitive, false = case-insensitive, omit = smart-case
includeHiddenNoInclude hidden files and directories
maxCharactersNoMaximum characters in the result. Truncated with summary if exceeded.
followSymlinksNoFollow symbolic links

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden. It does disclose a genuinely useful trait absent from structured data — the result contains paths only, not matching lines — but says nothing about permissions, read-only safety, pagination/truncation behavior (beyond what maxCharacters states in the schema), or hidden/ignored file traversal side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero filler, and the tool's action plus its return contract are front-loaded. Nothing could be removed without losing signal.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 15 parameters, no annotations, and no output schema, the description does cover the return format, which is the biggest gap an absent output schema creates. But for a tool that overlaps heavily with search, search-count, and list-files, it offers no routing guidance, and no behavioral caveats around ignore rules, symlinks, or hidden files.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% across all 15 parameters, so the schema already documents glob, path, sortBy, invertMatch, noIgnore, and the rest. The description only echoes the invertMatch idea ('or do not match') and adds no syntax, default, or interaction details beyond the schema. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List files that match... a pattern using ripgrep') and pins the output contract ('file paths only, no line content'), which functionally separates it from search and search-count. It stops short of naming any sibling explicitly, so differentiation is inferable rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The output distinction ('paths only, no line content') implies when to prefer this over a content-returning search, and 'or do not match' hints at the invert case. However, there is no explicit when-to-use, when-not-to-use, or named alternative among search, search-count, and list-files.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 6 tool updatesv1.2.0
    • First observedlist-file-types
    • First observedlist-files
    • First observedsearch
    • First observedsearch-and-replace
    • First observedsearch-count
    • First observedsearch-files
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored across 6 tools

Disambiguation5/5

Each tool exposes a distinct ripgrep operation: content search, count, file-list matching, all-file listing, file-type listing, and a read-only replace preview. Descriptions clearly differentiate outputs and use cases, leaving minimal risk of misselection.

Naming Consistency4/5

Names follow a lowercase-hyphenated convention (search, search-count, search-files, list-files, list-file-types), which is readable and mostly predictable. Minor inconsistencies exist: 'search' is a bare verb and 'search-and-replace' uses a compound phrase rather than a strict verb_noun pattern.

Tool Count5/5

Six tools are well-scoped for a ripgrep wrapper, covering the core search, count, listing, and preview operations without redundancy. Each tool earns its place and the set avoids bloat.

Completeness4/5

The surface covers ripgrep's main search and inspection workflows: pattern search, counting, file matching, full file listing, file-type enumeration, and replace preview. A minor gap is the lack of an actual file-modification tool, but the read-only design is clearly intentional.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • ripgrep-mcp

    shk1447
    A
    license
    A
    quality
    D
    maintenance
    Provides ripgrep search capabilities to MCP clients like Claude, enabling high-performance text searches across files on your system.
    5
    9 npm
    MIT

  • large-repo-mcp-server

    ErenAri
    A
    license
    Not graded
    quality
    C
    maintenance
    A stdio-based MCP server for fast, bounded search and navigation of large code repositories using ripgrep, with tools for project-wide search, symbol lookup, file listing, and code reading.
    5 npm
    1
    MIT