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)

Method 2: From Source

Method 3: Direct from GitHub

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:

Alternative: Using npx (no global install needed)

Local Development Setup

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

Verification

Test that the server is working:

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:

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:

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

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

1. "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"]

2. "Permission denied" error

   • Check file permissions: chmod +x build/index.js

   • Rebuild the project: npm run build

3. MCP server not appearing in Claude

   • Verify JSON syntax in configuration file

   • Restart Claude Desktop completely

   • Check that the command path is correct

4. "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:

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