Grep MCP Server

MCP Server for Grep

A Model Context Protocol (MCP) server that provides powerful text search capabilities using the grep command-line utility. This server allows you to search for patterns in files and directories using both natural language descriptions and direct regex patterns.

Features

🧠 Natural Language Search

Describe what you're looking for in plain English
Automatic conversion to appropriate regex patterns
Built-in patterns for common searches (emails, URLs, phone numbers, etc.)

🔍 Advanced Search Capabilities

Direct regex pattern matching
Recursive directory searching
File extension filtering
Case-sensitive/insensitive search
Whole word matching
Context line display
Match counting
File listing with matches

🛡️ Security First

Safe command execution using child_process.spawn
Input validation with Zod schemas
No shell injection vulnerabilities
Path validation and sanitization

Installation

Method 1: NPM Installation (Recommended)

# Install globally
npm install -g @247arjun/mcp-grep

# Or install locally in your project
npm install @247arjun/mcp-grep

Method 2: From Source

# Clone the repository
git clone https://github.com/247arjun/mcp-grep.git
cd mcp-grep

# Install dependencies
npm install

# Build the project
npm run build

# Optional: Link globally
npm link

Method 3: Direct from GitHub

# Install directly from GitHub
npm install -g git+https://github.com/247arjun/mcp-grep.git

Configuration

Claude Desktop Setup

Add to your Claude Desktop configuration file:

Location:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

Configuration:

{
  "mcpServers": {
    "mcp-grep": {
      "command": "mcp-grep",
      "args": []
    }
  }
}

Alternative: Using npx (no global install needed)

{
  "mcpServers": {
    "mcp-grep": {
      "command": "npx",
      "args": ["@247arjun/mcp-grep"]
    }
  }
}

Local Development Setup

{
  "mcpServers": {
    "mcp-grep": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-grep/build/index.js"]
    }
  }
}

After adding the configuration, restart Claude Desktop to load the MCP server.

Verification

Test that the server is working:

# Test the built server
node build/index.js

# Should show: "Grep MCP Server running on stdio"
# Press Ctrl+C to exit

Available Tools

1. `grep_search_intent`

Search using natural language descriptions.

Parameters:

intent (string): Plain English description (e.g., "email addresses", "TODO comments")
target (string): File or directory path to search
case_sensitive (boolean, optional): Case-sensitive search (default: false)
max_results (number, optional): Limit number of results
show_context (boolean, optional): Show surrounding lines (default: false)
context_lines (number, optional): Number of context lines (default: 2)

Example:

{
  "intent": "email addresses",
  "target": "./src",
  "show_context": true,
  "context_lines": 1
}

2. `grep_regex`

Search using direct regex patterns.

Parameters:

pattern (string): Regular expression pattern
target (string): File or directory path to search
case_sensitive (boolean, optional): Case-sensitive search
whole_words (boolean, optional): Match whole words only
invert_match (boolean, optional): Show non-matching lines
max_results (number, optional): Limit results
show_context (boolean, optional): Show context lines
context_lines (number, optional): Context line count
file_extensions (array, optional): Filter by file extensions

Example:

{
  "pattern": "function\\s+\\w+\\s*\\(",
  "target": "./src",
  "file_extensions": ["js", "ts"],
  "show_context": true
}

3. `grep_count`

Count matches for a pattern.

Parameters:

pattern (string): Pattern to count
target (string): Search target
case_sensitive (boolean, optional): Case sensitivity
whole_words (boolean, optional): Whole word matching
by_file (boolean, optional): Show count per file
file_extensions (array, optional): File extension filter

4. `grep_files_with_matches`

List files containing the pattern.

Parameters:

pattern (string): Search pattern
target (string): Directory to search
case_sensitive (boolean, optional): Case sensitivity
whole_words (boolean, optional): Whole word matching
file_extensions (array, optional): File extensions to include
exclude_patterns (array, optional): File patterns to exclude

5. `grep_advanced`

Execute grep with custom arguments (advanced users).

Parameters:

args (array): Array of grep arguments (excluding 'grep' itself)

Built-in Natural Language Patterns

The server recognizes these natural language intents:

Communication

"email", "email address", "emails" → Email address pattern
"url", "urls", "website", "link", "links" → URL pattern
"phone", "phone number", "phone numbers" → Phone number pattern

Network

"ip", "ip address", "ip addresses" → IPv4 address pattern

Data Types

"number", "numbers", "integer", "integers" → Numeric patterns
"date", "dates" → Date patterns

Code Patterns

"function", "functions" → Function declarations
"class", "classes" → Class definitions
"import", "imports" → Import statements
"export", "exports" → Export statements
"comment", "comments" → Comment lines
"todo", "todos" → TODO/FIXME/HACK comments

Error Patterns

"error", "errors" → Error messages
"warning", "warnings" → Warning messages

Usage Examples

Search for email addresses in a project

{
  "tool": "grep_search_intent",
  "intent": "email addresses",
  "target": "./src",
  "show_context": true
}

Find all TODO comments

{
  "tool": "grep_search_intent", 
  "intent": "todo comments",
  "target": "./",
  "file_extensions": ["js", "ts", "py"]
}

Search for function definitions with regex

{
  "tool": "grep_regex",
  "pattern": "^\\s*function\\s+\\w+",
  "target": "./src",
  "file_extensions": ["js"]
}

Count occurrences of a word

{
  "tool": "grep_count",
  "pattern": "async",
  "target": "./src",
  "by_file": true
}

List files containing import statements

{
  "tool": "grep_files_with_matches",
  "pattern": "^import",
  "target": "./src",
  "file_extensions": ["js", "ts"]
}

Development

Build and Run

# Development with auto-rebuild
npm run dev

# Production build
npm run build

# Start the server
npm start

Project Structure

mcp-grep/
├── src/
│   └── index.ts          # Main server implementation
├── build/                # Compiled JavaScript output
├── package.json          # Project configuration
├── tsconfig.json         # TypeScript configuration
└── README.md            # This file

Troubleshooting

Common Issues

"Command not found" error
- Ensure mcp-grep is installed globally: npm install -g @247arjun/mcp-grep
- Or use npx: "command": "npx", "args": ["@247arjun/mcp-grep"]
"Permission denied" error
- Check file permissions: chmod +x build/index.js
- Rebuild the project: npm run build
MCP server not appearing in Claude
- Verify JSON syntax in configuration file
- Restart Claude Desktop completely
- Check that the command path is correct
"grep command not found"
- Install grep on your system (usually pre-installed on macOS/Linux)
- Windows users: Install via WSL or use Git Bash

Debugging

Enable verbose logging by setting environment variable:

# For development
DEBUG=1 node build/index.js

# Test with sample input
echo '{"jsonrpc": "2.0", "method": "initialize", "params": {}}' | node build/index.js

Security Notes

Uses spawn with shell: false to prevent command injection
Validates all file paths before execution
Blocks potentially dangerous grep flags in advanced mode
Input validation with Zod schemas
No access to system files outside specified targets

Deploy Server

HTTP connection URL

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

Tools

Provides powerful text search capabilities using the grep command-line utility, allowing users to search files and directories using both natural language descriptions and regex patterns.

Related MCP Servers

MCP Ripgrep Server
mcollina
A
security
A
license
A
quality
Provides ripgrep search capabilities to MCP clients like Claude, allowing high-performance text searches across files on your system.
Last updated -
5
312
30
MIT License
MCP-Grep
erniebrodeur
-
security
A
license
-
quality
A server implementation that exposes grep functionality through the Model Context Protocol, allowing MCP-compatible clients to search for patterns in files using regular expressions.
Last updated -
13
GPL 3.0
Everything Search MCP Server
aripo99
-
security
-
license
-
quality
Provides fast file searching capabilities across Windows, macOS, and Linux operating systems using platform-specific search technologies.
Last updated -
MIT License
Greply MCP Server
AnthonyRuffino
A
security
F
license
A
quality
Enables file and directory searching through the greply CLI tool with configurable search options like context lines, case sensitivity, and pattern matching. Provides direct access to powerful grep-like functionality from MCP-compatible clients.
Last updated -
2
8

View all related MCP servers

MCP Server for Grep

Features

🧠 Natural Language Search

🔍 Advanced Search Capabilities

🛡️ Security First

Installation

Method 1: NPM Installation (Recommended)

Method 2: From Source

Method 3: Direct from GitHub

Configuration

Claude Desktop Setup

Verification

Available Tools

1. grep_search_intent

2. grep_regex

3. grep_count

4. grep_files_with_matches

5. grep_advanced

Built-in Natural Language Patterns

Communication

Network

Data Types

Code Patterns

Error Patterns

Usage Examples

Search for email addresses in a project

Find all TODO comments

Search for function definitions with regex

Count occurrences of a word

List files containing import statements

Development

Build and Run

Project Structure

Troubleshooting

Common Issues

Debugging

Security Notes

Tools

Related MCP Servers

MCP Ripgrep Server

MCP-Grep

Everything Search MCP Server

Greply MCP Server

New MCP Servers

MCP directory API

1. `grep_search_intent`

2. `grep_regex`

3. `grep_count`

4. `grep_files_with_matches`

5. `grep_advanced`