GrepAI MCP Integration with Claude Code

This skill covers integrating GrepAI with Claude Code using the Model Context Protocol (MCP).

When to Use This Skill

• Setting up GrepAI in Claude Code

• Enabling semantic search for AI coding assistant

• Configuring MCP server for Claude

• Troubleshooting Claude Code integration

What is MCP?

Model Context Protocol (MCP) allows AI assistants to use external tools. GrepAI provides an MCP server that gives Claude Code:

• Semantic code search

• Call graph analysis

• Index status monitoring

Prerequisites

• GrepAI installed

• Ollama running (or other embedding provider)

• Project indexed (grepai watch )

• Claude Code installed

Quick Setup

One command to add GrepAI to Claude Code:

claude mcp add grepai -- grepai mcp-serve

That's it! Claude Code can now use GrepAI tools.

Manual Configuration

If you prefer manual setup, add to Claude Code's MCP config:

Location

• macOS/Linux: ~/.claude/mcp.json

• Windows: %APPDATA%\Claude\mcp.json

Configuration

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

With Working Directory

If you want GrepAI to always use a specific project:

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

Verifying Installation

Check MCP Server

Start MCP server manually to test

grepai mcp-serve

You should see:

GrepAI MCP Server started Listening for requests...

In Claude Code

Ask Claude:

"Search the codebase for authentication code"

Claude should use the grepai_search tool.

Available Tools

Once connected, Claude Code has access to these tools:

Tool Description Parameters

grepai_search

Semantic code search query (required), limit , compact

grepai_trace_callers

Find function callers symbol (required), compact

grepai_trace_callees

Find function callees symbol (required), compact

grepai_trace_graph

Build call graph symbol (required), depth

grepai_index_status

Check index health verbose (optional)

Tool Usage Examples

Semantic Search

Claude request:

"Find code related to user authentication"

Claude uses:

{ "tool": "grepai_search", "parameters": { "query": "user authentication", "limit": 5, "compact": true } }

Trace Analysis

Claude request:

"What functions call the Login function?"

Claude uses:

{ "tool": "grepai_trace_callers", "parameters": { "symbol": "Login", "compact": true } }

Index Status

Claude request:

"Is the code index up to date?"

Claude uses:

{ "tool": "grepai_index_status", "parameters": { "verbose": true } }

Compact Mode

By default, MCP tools return compact JSON to minimize tokens:

{ "q": "authentication", "r": [ {"s": 0.92, "f": "src/auth/middleware.go", "l": "15-45"}, {"s": 0.85, "f": "src/auth/jwt.go", "l": "23-55"} ], "t": 2 }

This reduces token usage by ~80% compared to full content.

Working Directory

The MCP server uses the current working directory. Ensure:

• GrepAI is initialized in your project

• Index exists (run grepai watch first)

• Start Claude Code from your project directory

Option 1: Start Claude from Project Directory

cd /path/to/your/project claude # Claude Code now uses this directory

Option 2: Configure CWD in MCP Config

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

Multiple Projects

For multiple projects, you can:

Option 1: Multiple MCP Servers

{ "mcpServers": { "grepai-frontend": { "command": "grepai", "args": ["mcp-serve"], "cwd": "/path/to/frontend" }, "grepai-backend": { "command": "grepai", "args": ["mcp-serve"], "cwd": "/path/to/backend" } } }

Option 2: Use Workspaces

grepai workspace create my-workspace grepai workspace add my-workspace /path/to/frontend grepai workspace add my-workspace /path/to/backend

{ "mcpServers": { "grepai": { "command": "grepai", "args": ["mcp-serve", "--workspace", "my-workspace"] } } }

Troubleshooting

Tool Not Available

❌ Problem: Claude doesn't see GrepAI tools

✅ Solutions:

• Restart Claude Code after config changes

• Check MCP config syntax (valid JSON)

• Verify grepai is in PATH

• Test: grepai mcp-serve manually

Search Returns No Results

❌ Problem: Searches return empty

✅ Solutions:

• Ensure grepai watch has run

• Check working directory has .grepai/

• Verify index exists: grepai status

Connection Refused

❌ Problem: MCP server won't start

✅ Solutions:

• Check Ollama is running: curl http://localhost:11434/api/tags

• Verify config: cat .grepai/config.yaml

• Run grepai mcp-serve manually to see errors

Wrong Project Indexed

❌ Problem: Results from wrong codebase

✅ Solutions:

• Check cwd in MCP config

• Start Claude from correct directory

• Verify with grepai_index_status tool

Best Practices

• Keep index updated: Run grepai watch --background

• Use compact mode: Reduces token usage

• Set working directory: Explicit cwd in config

• Check status first: Use grepai_index_status

• Restart after config: Claude needs restart for MCP changes

Removing Integration

To remove GrepAI from Claude Code:

claude mcp remove grepai

Or manually edit ~/.claude/mcp.json and remove the grepai entry.

Output Format

Successful MCP setup:

✅ GrepAI MCP Integration Configured

Claude Code: ~/.claude/mcp.json Server: grepai mcp-serve Status: Connected

Available tools:

• grepai_search (semantic code search)
• grepai_trace_callers (find callers)
• grepai_trace_callees (find callees)
• grepai_trace_graph (call graphs)
• grepai_index_status (index health)

Claude can now search your code semantically!