🔍 GrepAI

Local AI-Powered Codebase Search MCP Server

GrepAI is a self-hosted Model Context Protocol (MCP) server that provides powerful codebase search and analysis capabilities. It runs entirely on your local machine, utilizing your NVIDIA GPU (via llama.cpp or vLLM) for AI-powered features.

Works with Claude Code, VS Code, and any MCP-compatible client.

---

⚡ Quick Start (One-Command Installation)

curl -fsSL https://raw.githubusercontent.com/vp2722/grepai/main/scripts/remote-install.sh | bash

Or clone and install manually:

git clone https://github.com/vp2722/grepai.git
cd grepai
./scripts/install.sh

---

📋 Complete End-to-End Setup Guide

Step 1: System Requirements

Minimum:

• Python 3.8+
• 8GB RAM
• 10GB disk space

Recommended (GPU):

• Python 3.10+
• NVIDIA GPU with 8GB+ VRAM
• CUDA 11.8+ or 12.x
• 16GB RAM

Check your system:

# Check Python version
python3 --version

# Check for NVIDIA GPU
nvidia-smi

# Check CUDA version
nvcc --version

Step 2: Clone the Repository

git clone https://github.com/vp2722/grepai.git
cd grepai

Step 3: Install Dependencies

# Install Python dependencies
pip install mcp fastapi uvicorn pydantic pyyaml aiofiles httpx

# Optional: Install LLM backend (choose one)
# For llama.cpp with CUDA support:
CMAKE_ARGS="-DLLAMA_CUBLAS=on" pip install llama-cpp-python

# For vLLM (requires NVIDIA GPU with 16GB+ VRAM):
pip install vllm

Step 4: Configure Claude Code MCP Settings

Create or edit ~/.claude/settings.json:

{
  "mcpServers": {
    "grepai": {
      "command": "/path/to/grepai/grepai-mcp",
      "args": [],
      "env": {
        "GREPAI_WORKSPACE": "/path/to/your/project"
      }
    }
  }
}

Example for your home directory:

{
  "mcpServers": {
    "grepai": {
      "command": "/home/YOUR_USERNAME/grepai/grepai-mcp",
      "args": [],
      "env": {
        "GREPAI_WORKSPACE": "/home/YOUR_USERNAME/your-project"
      }
    }
  }
}

Step 5: Test the MCP Server

# Test the server starts correctly
cd /path/to/grepai
echo '{"jsonrpc": "2.0", "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0.0"}}, "id": 1}' | python3 grepai-mcp

You should see a JSON response with "result" containing server info.

Step 6: Restart Claude Code

After configuring the MCP settings, restart Claude Code:

# Close and reopen Claude Code
claude

The GrepAI tools will now be available!

---

🛠️ Available MCP Tools

Tool	Description	Example Use
search_codebase	Search for patterns (text/regex) across all files	Find all TODO comments
read_file	Read file contents with line numbers	View a specific file
list_files	List files with glob pattern support	Find all Python files
get_file_info	Get file metadata (size, modified date)	Check file details
find_definition	Find function/class/variable definitions	Locate function source
find_references	Find all usages of a symbol	Track where a function is called
get_directory_structure	Get directory tree structure	Understand project layout
analyze_file	Extract file structure (imports, classes, functions)	Analyze file contents
search_and_replace_preview	Preview search/replace operations	Plan refactoring
get_workspace_info	Get workspace statistics	Project overview

---

🔧 Configuration

Environment Variables

Variable	Default	Description
GREPAI_WORKSPACE	Current directory	Root directory for searches
GREPAI_MAX_FILE_SIZE	10MB	Maximum file size to search
GREPAI_MAX_RESULTS	100	Maximum search results

Configuration File

Edit config/default.yaml to customize:

workspace:
  root: "."
  max_file_size: 10485760  # 10MB
  max_results: 100

ignore:
  directories:
    - .git
    - node_modules
    - __pycache__
    - .venv

llm:
  backend: auto  # auto, llama_cpp, vllm
  model:
    path: "models/model.gguf"
    context_size: 4096
    gpu_layers: -1  # -1 for all layers on GPU

---

🐳 Docker Setup

Quick Start with Docker

cd grepai/docker

# Set your workspace path
export WORKSPACE_PATH=/path/to/your/project

# Build and run
docker-compose up -d

Docker with GPU Support

Requires NVIDIA Container Toolkit:

# Install nvidia-container-toolkit (Ubuntu/Debian)
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

# Run with GPU
docker-compose up -d

---

🌐 Remote Access (Cloudflare Tunnel)

Securely expose your local GrepAI server to the internet:

# Run the tunnel setup
./scripts/setup-tunnel.sh

# Start the tunnel
./scripts/setup-tunnel.sh start

This creates a secure tunnel with:

• End-to-end encryption
• DDoS protection
• No port forwarding required

---

🤖 Using with Local LLM

Download a Model

# Create models directory
mkdir -p models

# Download Mistral 7B (recommended, ~4.4GB)
wget -O models/model.gguf https://huggingface.co/TheBloke/Mistral-7B-Instruct-v0.2-GGUF/resolve/main/mistral-7b-instruct-v0.2.Q4_K_M.gguf

Start the LLM API Server

python3 src/llm_backend.py --model models/model.gguf --host 127.0.0.1 --port 8000

Use with OpenAI-Compatible Clients

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="not-needed"
)

response = client.chat.completions.create(
    model="local-model",
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)

---

📁 Project Structure

grepai/
├── src/
│   ├── mcp_server.py       # Core MCP server (stdio)
│   ├── mcp_http_server.py  # MCP server (HTTP)
│   ├── llm_backend.py      # LLM integration
│   └── cli.py              # Command-line interface
├── config/
│   └── default.yaml        # Configuration
├── docker/
│   ├── Dockerfile          # Docker image
│   └── docker-compose.yml  # Docker Compose
├── scripts/
│   ├── install.sh          # Installation script
│   ├── remote-install.sh   # One-line installer
│   ├── setup-tunnel.sh     # Cloudflare tunnel
│   └── uninstall.sh        # Uninstaller
├── models/                 # Model storage
├── tests/                  # Unit tests
├── grepai-mcp              # Main launcher
├── requirements.txt        # Dependencies
└── README.md               # This file

---

🧪 Running Tests

pip install pytest pytest-asyncio
pytest tests/ -v

---

❓ Troubleshooting

MCP Server Not Starting

# Check if dependencies are installed
pip list | grep mcp

# Test manually
cd /path/to/grepai
python3 -c "from src.mcp_server import server; print('OK')"

GPU Not Detected

# Check NVIDIA driver
nvidia-smi

# Reinstall llama-cpp-python with CUDA
CMAKE_ARGS="-DLLAMA_CUBLAS=on" pip install llama-cpp-python --force-reinstall

Claude Code Not Finding Tools

1. Verify ~/.claude/settings.json exists and is valid JSON
2. Check the path to grepai-mcp is correct
3. Restart Claude Code completely

---

🗑️ Uninstallation

./scripts/uninstall.sh

Or manually:

rm -rf ~/.grepai
rm ~/.claude/settings.json  # Or edit to remove grepai entry

---

📄 License

MIT License - See LICENSE for details.

---

🙏 Acknowledgments

• MCP Protocol by Anthropic
• llama.cpp by Georgi Gerganov
• vLLM by vLLM Team

---

Made with ❤️ for the AI developer community