grepai-mcp-claude

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:

| 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!