Skip to main content
Glama

Grep MCP Server

by 247arjun
MIT License
10
1
  • Apple

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

  • 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

# 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

  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:

# 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

Related MCP Servers

  • A
    security
    A
    license
    A
    quality
    Enables text extraction from web pages and PDFs, and execution of predefined commands, enhancing content processing and automation capabilities.
    Last updated -
    3
    TypeScript
    MIT License
  • 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
    709
    23
    JavaScript
    MIT License
    • Apple
  • -
    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
    Python
    GPL 3.0
  • -
    security
    -
    license
    -
    quality
    Provides fast file searching capabilities across Windows, macOS, and Linux operating systems using platform-specific search technologies.
    Last updated -
    Python
    MIT License

View all related MCP servers

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/247arjun/mcp-grep'

If you have feedback or need assistance with the MCP directory API, please join our Discord server