---
title: Sourcebot MCP server (@sourcebot/mcp)
sidebarTitle: Sourcebot MCP server
---

The [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) is an open standard for providing context to LLMs. The [@sourcebot/mcp](https://www.npmjs.com/package/@sourcebot/mcp) package is a MCP server that enables LLMs to interface with your Sourcebot instance, enabling MCP clients like Cursor, Vscode, and others to have context over your entire codebase.

## Getting Started

<Steps>
    <Step title="Launch Sourcebot">
        Follow the [deployment guides](/docs/deployment/docker-compose) to launch Sourcebot and get your code indexed. The host url of your instance (e.g., `http://localhost:3000`) is passed to the MCP server via the `SOURCEBOT_HOST` url.

        If a host is not provided, then the server will fallback to using the demo instance hosted at https://demo.sourcebot.dev. You can see the list of repositories indexed [here](https://demo.sourcebot.dev/~/repos). Add additional repositories by [opening a PR](https://github.com/sourcebot-dev/sourcebot/blob/main/demo-site-config.json).
    </Step>

    <Step title="Create an API key">
        Create an API key to allow the MCP server to query your Sourcebot instance. To create an API key, login to your Sourcebot instance and navigate to **Settings -> API Keys**:

        ![API Keys UI](/images/api_key.png)

        Copy the API key and set it as the `SOURCEBOT_API_KEY` environment variable.
    </Step>

    <Step title="Install the MCP server">
        <Note>
            Ensure you have [Node.js](https://nodejs.org/en) >= v18.0.0 installed.
        </Note>
        Next, we can install the [@sourcebot/mcp](https://www.npmjs.com/package/@sourcebot/mcp) MCP server into any supported MCP client:
        
        <AccordionGroup>
            <Accordion title="Cursor">
                [Cursor MCP docs](https://docs.cursor.com/context/model-context-protocol)

                Go to: `Settings` -> `Cursor Settings` -> `MCP` -> `Add new global MCP server`

                Paste the following into your `~/.cursor/mcp.json` file. This will install Sourcebot globally within Cursor:

                ```json
                {
                    "mcpServers": {
                        "sourcebot": {
                            "command": "npx",
                            "args": ["-y", "@sourcebot/mcp@latest" ],
                            "env": {
                                "SOURCEBOT_HOST": "http://localhost:3000",
                                "SOURCEBOT_API_KEY": "your-api-key"
                            }
                        }
                    }
                }
                ```

                Replace `http://localhost:3000` with wherever your Sourcebot instance is hosted.
            </Accordion>
            <Accordion title="Windsurf">
                [Windsurf MCP docs](https://docs.windsurf.com/windsurf/mcp)

                Go to: `Windsurf Settings` -> `Cascade` -> `Add Server` -> `Add Custom Server`

                Paste the following into your `mcp_config.json` file:

                ```json
                {
                    "mcpServers": {
                        "sourcebot": {
                            "command": "npx",
                            "args": ["-y", "@sourcebot/mcp@latest" ],
                            "env": {
                                "SOURCEBOT_HOST": "http://localhost:3000",
                                "SOURCEBOT_API_KEY": "your-api-key"
                            }
                        }
                    }
                }
                ```

                Replace `http://localhost:3000` with wherever your Sourcebot instance is hosted.

            </Accordion>
            <Accordion title="VS Code">
                [VS Code MCP docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers)

                Add the following to your [.vscode/mcp.json](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server-to-your-workspace) file:
                
                ```json
                {
                    "servers": {
                        "sourcebot": {
                            "type": "stdio",
                            "command": "npx",
                            "args": ["-y", "@sourcebot/mcp@latest"],
                            "env": {
                                "SOURCEBOT_HOST": "http://localhost:3000",
                                "SOURCEBOT_API_KEY": "your-api-key"
                            }
                        }
                    }
                }
                ```

                Replace `http://localhost:3000` with wherever your Sourcebot instance is hosted.
            </Accordion>
            <Accordion title="Claude Code">
                [Claude Code MCP docs](https://docs.anthropic.com/en/docs/claude-code/tutorials#set-up-model-context-protocol-mcp)

                Run the following command:

                ```sh
                claude mcp add sourcebot -e SOURCEBOT_HOST=http://localhost:3000 -e SOURCEBOT_API_KEY=your-api-key -- npx -y @sourcebot/mcp@latest
                ```

                Replace `http://localhost:3000` with wherever your Sourcebot instance is hosted.
            </Accordion>
            <Accordion title="Claude Desktop">
                [Claude Desktop MCP docs](https://modelcontextprotocol.io/quickstart/user)

                Add the following to your `claude_desktop_config.json`:

                ```json
                {
                    "mcpServers": {
                        "sourcebot": {
                            "command": "npx",
                            "args": ["-y", "@sourcebot/mcp@latest"],
                            "env": {
                                "SOURCEBOT_HOST": "http://localhost:3000",
                                "SOURCEBOT_API_KEY": "your-api-key"
                            }
                        }
                    }
                }
                ```

                Replace `http://localhost:3000` with wherever your Sourcebot instance is hosted.
            </Accordion>
        </AccordionGroup>
    </Step>

    <Step title="Prompt the LLM">
        Tell your LLM to `use sourcebot` when prompting.
    </Step>

</Steps>


## Available Tools


### `search_code`

Fetches code that matches the provided regex pattern in `query`.

Parameters:
| Name                  | Required | Description                                                                                                                       |
|:----------------------|:---------|:----------------------------------------------------------------------------------------------------------------------------------|
| `query`               | yes      | Regex pattern to search for. Escape special characters and spaces with a single backslash (e.g., 'console\.log', 'console\ log'). |
| `filterByRepoIds`     | no       | Restrict search to specific repository IDs (from 'list_repos'). Leave empty to search all.                                        |
| `filterByLanguages`   | no       | Restrict search to specific languages (GitHub linguist format, e.g., Python, JavaScript).                                         |
| `caseSensitive`       | no       | Case sensitive search (default: false).                                                                                           |
| `includeCodeSnippets` | no       | Include code snippets in results (default: false).                                                                                |
| `maxTokens`           | no       | Max tokens to return (default: env.DEFAULT_MINIMUM_TOKENS).                                                                       |


### `list_repos`

Lists all repositories indexed by Sourcebot.

### `get_file_source`

Fetches the source code for a given file.

Parameters:
| Name         | Required | Description                                                      |
|:-------------|:---------|:-----------------------------------------------------------------|
| `fileName`   | yes      | The file to fetch the source code for.                           |
| `repoId`     | yes      | The Sourcebot repository ID.                                     |


## Environment Variables

| Name                     | Default                | Description                                       |
|:-------------------------|:-----------------------|:--------------------------------------------------|
| `SOURCEBOT_HOST`         | http://localhost:3000  | URL of your Sourcebot instance.                   |
| `SOURCEBOT_API_KEY`      | -                      | Sourcebot API key.                                |
| `DEFAULT_MINIMUM_TOKENS` | 10000                  | Minimum number of tokens to return in responses.  |
| `DEFAULT_MATCHES`        | 10000                  | Number of code matches to fetch per search.       |
| `DEFAULT_CONTEXT_LINES`  | 5                      | Lines of context to include above/below matches.  |
