grepai-mcp-cursor

SKILL.md

GrepAI MCP Integration with Cursor

This skill covers integrating GrepAI with Cursor IDE using the Model Context Protocol (MCP).

When to Use This Skill

Setting up GrepAI in Cursor

Enabling semantic search for Cursor AI

Configuring MCP for Cursor

Troubleshooting Cursor integration

What is Cursor?

Cursor is an AI-powered IDE that supports MCP for external tools. GrepAI integration gives Cursor's AI:

Semantic code search beyond simple text matching

Call graph analysis for understanding dependencies

Index-based code navigation

Prerequisites

GrepAI installed

Ollama running (or other embedding provider)

Project indexed (grepai watch)

Cursor IDE installed

Configuration

Step 1: Create MCP Config File

Create .cursor/mcp.json in your project root:

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

Step 2: Restart Cursor

Close and reopen Cursor for the config to take effect.

Step 3: Verify

Ask Cursor's AI:

"Search the codebase for authentication"

Cursor should use the grepai_search tool.

Global Configuration

For GrepAI in all Cursor projects, use global config:

Location

macOS: ~/.cursor/mcp.json

Linux: ~/.cursor/mcp.json

Windows: %APPDATA%\Cursor\mcp.json

Content

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

Per-Project Configuration

For project-specific settings:

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

Available Tools

Once configured, Cursor has access to:

Tool
Description

grepai_search
Semantic code search

grepai_trace_callers
Find function callers

grepai_trace_callees
Find function callees

grepai_trace_graph
Build call graphs

grepai_index_status
Check index health

Usage Examples

Finding Code

Ask Cursor:

"Find code that handles user login"

Cursor uses grepai_search to find semantically related code.

Understanding Dependencies

Ask Cursor:

"What functions call validateToken?"

Cursor uses grepai_trace_callers to show all callers.

Code Navigation

Ask Cursor:

"Show me the call graph for processPayment"

Cursor uses grepai_trace_graph to display dependencies.

Cursor Settings Integration

Enable MCP in Settings

Open Cursor Settings (Cmd+, / Ctrl+,)

Search for "MCP"

Ensure MCP is enabled

Verify MCP Status

Open Command Palette (Cmd+Shift+P / Ctrl+Shift+P)

Search "MCP"

Check connected servers

Windsurf Configuration

Windsurf uses the same MCP format as Cursor:

Location

Create .windsurf/mcp.json:

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

Multiple Projects Setup

Option 1: Separate Configs

Each project has its own .cursor/mcp.json with appropriate cwd.

Option 2: Workspaces

# Create workspace
grepai workspace create dev
grepai workspace add dev /path/to/project1
grepai workspace add dev /path/to/project2

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

Environment Variables

If GrepAI uses environment variables (like API keys):

{
  "mcpServers": {
    "grepai": {
      "command": "grepai",
      "args": ["mcp-serve"],
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Better: Set environment variables in your shell profile instead.

Troubleshooting

MCP Not Recognized

❌ Problem: Cursor doesn't see GrepAI tools

✅ Solutions:

Check file location: .cursor/mcp.json in project root

Verify JSON syntax (no trailing commas)

Restart Cursor completely

Check grepai is in PATH

Search Returns Nothing

❌ Problem: Empty search results

✅ Solutions:

Ensure index exists: grepai status

Run grepai watch first

Verify working directory

Connection Errors

❌ Problem: MCP connection failed

✅ Solutions:

Test manually: grepai mcp-serve

Check Ollama: curl http://localhost:11434/api/tags

Look at Cursor's developer console for errors

Wrong Results

❌ Problem: Results from wrong project

✅ Solutions:

Set explicit cwd in config

Check you opened the right folder in Cursor

Use grepai_index_status to verify

Performance Tips

Background daemon: Keep grepai watch --background running

Use compact mode: MCP tools use compact by default

Limit results: AI will request appropriate limits

Index regularly: Especially after git pull

Comparison: Cursor vs Claude Code

Feature
Cursor
Claude Code

Config location
.cursor/mcp.json
~/.claude/mcp.json

Setup command
Manual JSON
claude mcp add

Project scope
Per-project or global
Global

IDE integration
Native
Terminal

Best Practices

Version control: Add .cursor/mcp.json to git (without secrets)

Team setup: Document MCP config in README

Keep index fresh: Run watch daemon

Test locally: Verify grepai mcp-serve works first

Use workspaces: For multi-project setups

Removing Integration

Delete .cursor/mcp.json and restart Cursor.

Or remove just GrepAI:

{
  "mcpServers": {
    // Remove grepai entry
  }
}

Output Format

Successful Cursor setup:

✅ GrepAI MCP Integration for Cursor

   Config: .cursor/mcp.json
   Server: grepai mcp-serve
   Status: Ready

   Available tools:
   - grepai_search
   - grepai_trace_callers
   - grepai_trace_callees
   - grepai_trace_graph
   - grepai_index_status

   Cursor AI can now search your code semantically!

   Test: Ask Cursor "search for authentication code"