sourcegraph-mcp

Model Context Protocol server for searching code via SourceGraph's GraphQL API. Leverages SourceGraph's indexed symbol search for fast, precise code navigation. Works with both local and cloud SourceGraph instances.

Why Use This?

Search your entire codebase instantly using SourceGraph's indexed search:

• Lightning Fast: Symbol lookups in <100ms using indexed search
• Precise: Find exact definitions vs references/usages separately
• Cost-effective: ~400 tokens per search vs 50k+ tokens loading files
• Comprehensive: Search across all repos, branches, and languages

Key Features

🎯 Symbol Search (Indexed)

• Find Definitions: Locate where functions, classes, methods are declared
• Find References: See all places where a symbol is used
• Fast Lookups: Uses SourceGraph's pre-built symbol index
• Returns: Exact file path, line number, and column position

🔍 Code Search

• Text Search: Find any text pattern across your codebase
• Regex Search: Complex pattern matching with full regex support
• Filters: By repository, file path, language, and more

Installation

Quick Start (with pipx - Recommended)

pipx install sourcegraph-mcp

This installs the sourcegraph-mcp command globally and handles all dependencies automatically.

Verify Installation

which sourcegraph-mcp
# Should show: /Users/yourusername/.local/bin/sourcegraph-mcp

Configuration

IMPORTANT: Replace the URL and token with your actual SourceGraph instance details.

Option 1: Environment Variables (Recommended)

export SOURCEGRAPH_URL=http://localhost:3370
export SOURCEGRAPH_TOKEN=sgp_your_token_here

Option 2: Config File

Create config.json:

{
  "sourcegraph_url": "http://localhost:3370",
  "access_token": "sgp_your_token_here",
  "timeout": 30
}

Option 3: CLI Arguments

sourcegraph-mcp --url http://localhost:3370 --token sgp_your_token_here

Setup with MCP Clients

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

IMPORTANT: Replace the URL and token with your actual SourceGraph instance details.

{
  "mcpServers": {
    "sourcegraph": {
      "command": "sourcegraph-mcp",
      "env": {
        "SOURCEGRAPH_URL": "http://localhost:3370",
        "SOURCEGRAPH_TOKEN": "sgp_your_token_here"
      }
    }
  }
}

Claude Code

Important: First install with pipx install sourcegraph-mcp, then configure.

IMPORTANT: Replace the URL and token with your actual SourceGraph instance details.

Option 1: User-Wide (Recommended - No Permission Prompts)

Add to ~/.claude.json:

{
  "mcpServers": {
    "sourcegraph": {
      "command": "sourcegraph-mcp",
      "env": {
        "SOURCEGRAPH_URL": "http://localhost:3370",
        "SOURCEGRAPH_TOKEN": "sgp_your_token_here"
      }
    }
  },
  "permissions": {
    "allow": [
      "mcp__sourcegraph__*"
    ]
  }
}

Note: If sourcegraph-mcp is not in your PATH, use the full path:

"command": "/Users/yourusername/.local/bin/sourcegraph-mcp"

Restart Claude Code and verify with /mcp command.

Option 2: Project-Specific

Create .mcp.json in your project root:

{
  "mcpServers": {
    "sourcegraph": {
      "command": "sourcegraph-mcp",
      "env": {
        "SOURCEGRAPH_URL": "http://localhost:3370",
        "SOURCEGRAPH_TOKEN": "sgp_your_token_here"
      }
    }
  }
}

Then add permissions to .claude/settings.local.json:

{
  "permissions": {
    "allow": [
      "mcp__sourcegraph__find_symbol_definition",
      "mcp__sourcegraph__find_symbol_references",
      "mcp__sourcegraph__search_sourcegraph",
      "mcp__sourcegraph__search_sourcegraph_regex",
      "mcp__sourcegraph__get_sourcegraph_config"
    ]
  },
  "enableAllProjectMcpServers": true,
  "enabledMcpjsonServers": ["sourcegraph"]
}

Important: Permission format must use mcp__servername__toolname with double underscores, not colons.

Note: The permissions section above is specific to Claude Code. Other MCP clients may not require explicit permissions or may use different permission systems.

Other MCP Clients (Cursor, Windsurf, Zed, Cline, etc.)

Most MCP clients use similar configuration. The general pattern is:

1. Install: pipx install sourcegraph-mcp
2. Add to your client's MCP config file:

{
  "mcpServers": {
    "sourcegraph": {
      "command": "sourcegraph-mcp",  // or full path: ~/.local/bin/sourcegraph-mcp
      "env": {
        "SOURCEGRAPH_URL": "http://localhost:3370",
        "SOURCEGRAPH_TOKEN": "sgp_your_token_here"
      }
    }
  }
}

Refer to your client's documentation for the config file location.

Community contributions welcome! If you've successfully set this up with another client, please submit a PR with instructions.

Usage

Once configured, your AI assistant can leverage SourceGraph's indexed search:

Symbol Definitions (Fast Lookups)

"Find where the ProcessOrder function is defined"
"Where is the CustomerService class declared?"
"Show me the definition of HandleRequest method"
"Locate the API_KEY constant definition"

Symbol References (Find Usages)

"Find all calls to ProcessOrder"
"Where is CustomerService used?"
"Show me all references to API_KEY"
"Find everywhere HandleRequest is called"

General Code Search

"Search for authentication code"
"Find TODO comments in C# files"
"Show error handling patterns in the api directory"

Available Tools

1. find_symbol_definition

Find where symbols are defined (declarations). Returns exact file path and line number.

Best for:

• "Where is X defined?"
• "Go to definition of Y"
• "Show me the declaration of Z"

Returns:

• File path
• Line number
• Column position
• Symbol kind (function, class, method, etc.)

2. find_symbol_references

Find where symbols are used (references/calls). Returns all usage locations.

Best for:

• "Where is X called?"
• "Find all uses of Y"
• "Show me references to Z"

Returns:

• File paths and line numbers for each usage
• Code context around each reference

3. search_sourcegraph

General text-based code search with full query syntax.

Query syntax:

• repo:owner/name - Filter by repository
• file:pattern - Filter by file path
• lang:language - Filter by programming language
• case:yes - Case-sensitive search

4. search_sourcegraph_regex

Search using regular expressions for complex pattern matching.

5. get_sourcegraph_config

View current configuration (useful for debugging).

Performance Advantages

Symbol Search (Indexed)

• ✅ <100ms: Instant lookups using pre-built index
• ✅ Precise: Distinguishes definitions from references
• ✅ Scalable: Works across millions of lines of code

Text Search

• ✅ Fast: Leverages SourceGraph's Zoekt indexing
• ✅ Flexible: Full regex and filter support
• ✅ Comprehensive: Searches across all content

vs Loading Files into Context

• 400 tokens per search vs 50k+ tokens loading files
• Instant results vs waiting for file loads
• Pinpoint accuracy vs reading through entire files

Getting a SourceGraph Token

1. Navigate to your SourceGraph instance
2. Go to Settings → Access tokens
3. Click "Generate new token"
4. Copy the token (starts with sgp_)

Local Development

# Clone and install
git clone https://github.com/dalebrubaker/sourcegraph-mcp
cd sourcegraph-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

# Test configuration
python test_connection.py

# Run with config file
python server.py

# Run with CLI args
python server.py --url http://localhost:3370 --token sgp_your_token_here

Troubleshooting

"Could not connect to MCP server"

• Verify SourceGraph is running and accessible
• Check URL format (include http:// or https://)
• Test token: curl -H "Authorization: token sgp_..." http://your-url/.api/graphql
• Verify installation: which sourcegraph-mcp should show the installed path
• If not in PATH, use full path in config: /Users/yourusername/.local/bin/sourcegraph-mcp

"Command not found"

• Make sure you installed with pipx install sourcegraph-mcp
• Check if ~/.local/bin is in your PATH: echo $PATH | grep .local/bin
• Try using the full path in your config instead of just sourcegraph-mcp

"No symbols found"

• Symbol search requires SourceGraph's symbol indexing to be enabled
• Check if your repositories have been indexed: Settings → Repositories → Indexing
• Symbol indexing may take time for large repos
• Try general code search as a fallback

Testing Your Setup

# Test connection and both search types
python test_connection.py

Example Queries

Finding Definitions

User: "Find where the LowerBound method is defined with file name and line number"

MCP Response:
## 1. `LowerBound` (method)
**File:** `src/Collections/SortedList.cs`
**Line:** 142
**Position:** Line 142, Column 8
**Repository:** `myorg/core-lib`

Finding References

User: "Show me all places where ProcessOrder is called"

MCP Response:
## 1. `OrderController.cs`
**Repository:** `myorg/api-service`
**URL:** https://sourcegraph.local/...

**Matches:**
- **Line 45:** `var result = await ProcessOrder(orderId);`
- **Line 87:** `return ProcessOrder(order);`

## 2. `OrderProcessor.cs`
...

License

MIT

Contributing

PRs welcome! Please open an issue first to discuss significant changes.

Roadmap

• [ ] Support for batch symbol lookups
• [ ] Cached symbol results for faster repeated queries
• [ ] Structural search support
• [ ] Commit and diff search tools
• [ ] Multi-repo symbol search optimization