|
| 1 | +--- |
| 2 | +title: Sourcebot MCP server (@sourcebot/mcp) |
| 3 | +sidebarTitle: Sourcebot MCP server |
| 4 | +--- |
| 5 | + |
| 6 | +<Note> |
| 7 | +This feature is only available when [self-hosting](/self-hosting) with [authentication](/self-hosting/more/authentication) disabled. |
| 8 | +</Note> |
| 9 | + |
| 10 | +The [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) is a 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. |
| 11 | + |
| 12 | +## Getting Started |
| 13 | + |
| 14 | +<Steps> |
| 15 | + <Step title="Launch Sourcebot"> |
| 16 | + Follow the self-hosting [quick start guide](/self-hosting/overview#quick-start-guide) 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. |
| 17 | + |
| 18 | + 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). |
| 19 | + </Step> |
| 20 | + |
| 21 | + <Step title="Install the MCP server"> |
| 22 | + <Note> |
| 23 | + Ensure you have [Node.js](https://nodejs.org/en) >= v18.0.0 installed. |
| 24 | + </Note> |
| 25 | + Next, we can install the [@sourcebot/mcp](https://www.npmjs.com/package/@sourcebot/mcp) MCP server into any supported MCP client: |
| 26 | + |
| 27 | + <AccordionGroup> |
| 28 | + <Accordion title="Cursor"> |
| 29 | + [Cursor MCP docs](https://docs.cursor.com/context/model-context-protocol) |
| 30 | + |
| 31 | + Go to: `Settings` -> `Cursor Settings` -> `MCP` -> `Add new global MCP server` |
| 32 | + |
| 33 | + Paste the following into your `~/.cursor/mcp.json` file. This will install Sourcebot globally within Cursor: |
| 34 | + |
| 35 | + ```json |
| 36 | + { |
| 37 | + "mcpServers": { |
| 38 | + "sourcebot": { |
| 39 | + "command": "npx", |
| 40 | + "args": ["-y", "@sourcebot/mcp@latest" ], |
| 41 | + "env": { |
| 42 | + "SOURCEBOT_HOST": "http://localhost:3000" |
| 43 | + } |
| 44 | + } |
| 45 | + } |
| 46 | + } |
| 47 | + ``` |
| 48 | + |
| 49 | + Replace `http://localhost:3000` with wherever your Sourcebot instance is hosted. |
| 50 | + </Accordion> |
| 51 | + <Accordion title="Windsurf"> |
| 52 | + [Windsurf MCP docs](https://docs.windsurf.com/windsurf/mcp) |
| 53 | + |
| 54 | + Go to: `Windsurf Settings` -> `Cascade` -> `Add Server` -> `Add Custom Server` |
| 55 | + |
| 56 | + Paste the following into your `mcp_config.json` file: |
| 57 | + |
| 58 | + ```json |
| 59 | + { |
| 60 | + "mcpServers": { |
| 61 | + "sourcebot": { |
| 62 | + "command": "npx", |
| 63 | + "args": ["-y", "@sourcebot/mcp@latest" ], |
| 64 | + "env": { |
| 65 | + "SOURCEBOT_HOST": "http://localhost:3000" |
| 66 | + } |
| 67 | + } |
| 68 | + } |
| 69 | + } |
| 70 | + ``` |
| 71 | + |
| 72 | + Replace `http://localhost:3000` with wherever your Sourcebot instance is hosted. |
| 73 | + |
| 74 | + </Accordion> |
| 75 | + <Accordion title="VS Code"> |
| 76 | + [VS Code MCP docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) |
| 77 | + |
| 78 | + Add the following to your [settings.json](https://code.visualstudio.com/docs/copilot/chat/mcp-servers): |
| 79 | + |
| 80 | + ```json |
| 81 | + { |
| 82 | + "mcp": { |
| 83 | + "servers": { |
| 84 | + "sourcebot": { |
| 85 | + "type": "stdio", |
| 86 | + "command": "npx", |
| 87 | + "args": ["-y", "@sourcebot/mcp@latest"] |
| 88 | + }, |
| 89 | + "env": { |
| 90 | + "SOURCEBOT_HOST": "http://localhost:3000" |
| 91 | + } |
| 92 | + } |
| 93 | + } |
| 94 | + } |
| 95 | + ``` |
| 96 | + |
| 97 | + Replace `http://localhost:3000` with wherever your Sourcebot instance is hosted. |
| 98 | + </Accordion> |
| 99 | + <Accordion title="Claude Code"> |
| 100 | + [Claude Code MCP docs](https://docs.anthropic.com/en/docs/claude-code/tutorials#set-up-model-context-protocol-mcp) |
| 101 | + |
| 102 | + Run the following command: |
| 103 | + |
| 104 | + ```sh |
| 105 | + claude mcp add sourcebot -e SOURCEBOT_HOST=http://localhost:3000 -- npx -y @sourcebot/mcp@latest |
| 106 | + ``` |
| 107 | + |
| 108 | + Replace `http://localhost:3000` with wherever your Sourcebot instance is hosted. |
| 109 | + </Accordion> |
| 110 | + <Accordion title="Claude Desktop"> |
| 111 | + [Claude Desktop MCP docs](https://modelcontextprotocol.io/quickstart/user) |
| 112 | + |
| 113 | + Add the following to your `claude_desktop_config.json`: |
| 114 | + |
| 115 | + ```json |
| 116 | + { |
| 117 | + "mcpServers": { |
| 118 | + "sourcebot": { |
| 119 | + "command": "npx", |
| 120 | + "args": ["-y", "@sourcebot/mcp@latest"], |
| 121 | + "env": { |
| 122 | + "SOURCEBOT_HOST": "http://localhost:3000" |
| 123 | + } |
| 124 | + } |
| 125 | + } |
| 126 | + } |
| 127 | + ``` |
| 128 | + |
| 129 | + Replace `http://localhost:3000` with wherever your Sourcebot instance is hosted. |
| 130 | + </Accordion> |
| 131 | + </AccordionGroup> |
| 132 | + </Step> |
| 133 | + |
| 134 | + <Step title="Prompt the LLM"> |
| 135 | + Tell your LLM to `use sourcebot` when prompting. |
| 136 | + </Step> |
| 137 | + |
| 138 | +</Steps> |
| 139 | + |
| 140 | + |
| 141 | +## Available Tools |
| 142 | + |
| 143 | + |
| 144 | +### `search_code` |
| 145 | + |
| 146 | +Fetches code that matches the provided regex pattern in `query`. |
| 147 | + |
| 148 | +Parameters: |
| 149 | +| Name | Required | Description | |
| 150 | +|:----------------------|:---------|:----------------------------------------------------------------------------------------------------------------------------------| |
| 151 | +| `query` | yes | Regex pattern to search for. Escape special characters and spaces with a single backslash (e.g., 'console\.log', 'console\ log'). | |
| 152 | +| `filterByRepoIds` | no | Restrict search to specific repository IDs (from 'list_repos'). Leave empty to search all. | |
| 153 | +| `filterByLanguages` | no | Restrict search to specific languages (GitHub linguist format, e.g., Python, JavaScript). | |
| 154 | +| `caseSensitive` | no | Case sensitive search (default: false). | |
| 155 | +| `includeCodeSnippets` | no | Include code snippets in results (default: false). | |
| 156 | +| `maxTokens` | no | Max tokens to return (default: env.DEFAULT_MINIMUM_TOKENS). | |
| 157 | + |
| 158 | + |
| 159 | +### `list_repos` |
| 160 | + |
| 161 | +Lists all repositories indexed by Sourcebot. |
| 162 | + |
| 163 | +### `get_file_source` |
| 164 | + |
| 165 | +Fetches the source code for a given file. |
| 166 | + |
| 167 | +Parameters: |
| 168 | +| Name | Required | Description | |
| 169 | +|:-------------|:---------|:-----------------------------------------------------------------| |
| 170 | +| `fileName` | yes | The file to fetch the source code for. | |
| 171 | +| `repoId` | yes | The Sourcebot repository ID. | |
| 172 | + |
| 173 | + |
| 174 | +## Environment Variables |
| 175 | + |
| 176 | +| Name | Default | Description | |
| 177 | +|:-------------------------|:-----------------------|:--------------------------------------------------| |
| 178 | +| `SOURCEBOT_HOST` | http://localhost:3000 | URL of your Sourcebot instance. | |
| 179 | +| `DEFAULT_MINIMUM_TOKENS` | 10000 | Minimum number of tokens to return in responses. | |
| 180 | +| `DEFAULT_MATCHES` | 10000 | Number of code matches to fetch per search. | |
| 181 | +| `DEFAULT_CONTEXT_LINES` | 5 | Lines of context to include above/below matches. | |
0 commit comments