> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sourcebot.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Sourcebot MCP server (@sourcebot/mcp)
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
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` environment variable.
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**:
Copy the API key and set it as the `SOURCEBOT_API_KEY` environment variable.
Ensure you have [Node.js](https://nodejs.org/en) >= v18.0.0 installed.
Next, we can install the [@sourcebot/mcp](https://www.npmjs.com/package/@sourcebot/mcp) MCP server into any supported MCP client:
[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 theme={null}
{
"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.
[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 theme={null}
{
"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.
[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 theme={null}
{
"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.
[Claude Code MCP docs](https://docs.anthropic.com/en/docs/claude-code/tutorials#set-up-model-context-protocol-mcp)
Run the following command:
```sh theme={null}
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.
[Claude Desktop MCP docs](https://modelcontextprotocol.io/quickstart/user)
Add the following to your `claude_desktop_config.json`:
```json theme={null}
{
"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.
Tell your LLM to `use sourcebot` when prompting.
## Available Tools
### `search_code`
Searches for code that matches the provided search query as a substring by default, or as a regular expression if `useRegex` is true.
Parameters:
| Name | Required | Description |
| :-------------------- | :------- | :--------------------------------------------------------------------------------------------------- |
| `query` | yes | The search pattern to match against code contents. Do not escape quotes in your query. |
| `useRegex` | no | Whether to use regular expression matching. When false, substring matching is used (default: false). |
| `filterByRepos` | no | Scope the search to specific repositories. |
| `filterByLanguages` | no | Scope the search to specific languages. |
| `filterByFilepaths` | no | Scope the search to specific filepaths. |
| `caseSensitive` | no | Whether the search should be case sensitive (default: false). |
| `includeCodeSnippets` | no | Whether to include code snippets in the response (default: false). |
| `ref` | no | Commit SHA, branch or tag name to search on. If not provided, defaults to the default branch. |
| `maxTokens` | no | The maximum number of tokens to return (default: 10000). |
### `list_repos`
Lists repositories indexed by Sourcebot with optional filtering and pagination.
Parameters:
| Name | Required | Description |
| :---------- | :------- | :----------------------------------------------------------------------------- |
| `query` | no | Filter repositories by name (case-insensitive). |
| `page` | no | Page number for pagination (min 1, default: 1). |
| `perPage` | no | Results per page for pagination (min 1, max 100, default: 30). |
| `sort` | no | Sort repositories by 'name' or 'pushed' (most recent commit). Default: 'name'. |
| `direction` | no | Sort direction: 'asc' or 'desc' (default: 'asc'). |
### `read_file`
Reads the source code for a given file.
Parameters:
| Name | Required | Description |
| :----- | :------- | :----------------------------------------------------------------------------------------------------- |
| `repo` | yes | The repository name. |
| `path` | yes | The path to the file. |
| `ref` | no | Commit SHA, branch or tag name to fetch the source code for. If not provided, uses the default branch. |
### `list_tree`
Lists files and directories from a repository path. Can be used as a directory listing tool (`depth: 1`) or a repo-tree tool (`depth > 1`).
Parameters:
| Name | Required | Description |
| :------------------- | :------- | :------------------------------------------------------------------------------------------- |
| `repo` | yes | The name of the repository to list files from. |
| `path` | no | Directory path (relative to repo root). If omitted, the repo root is used. |
| `ref` | no | Commit SHA, branch or tag name to list files from. If not provided, uses the default branch. |
| `depth` | no | Number of directory levels to traverse below `path` (min 1, max 10, default: 1). |
| `includeFiles` | no | Whether to include file entries in the output (default: true). |
| `includeDirectories` | no | Whether to include directory entries in the output (default: true). |
| `maxEntries` | no | Maximum number of entries to return before truncating (min 1, max 10000, default: 1000). |
### `list_commits`
Get a list of commits for a given repository.
Parameters:
| Name | Required | Description |
| :-------- | :------- | :------------------------------------------------------------------------------------------------------------------------- |
| `repo` | yes | The name of the repository to list commits for. |
| `query` | no | Search query to filter commits by message content (case-insensitive). |
| `since` | no | Show commits more recent than this date. Supports ISO 8601 (e.g., '2024-01-01') or relative formats (e.g., '30 days ago'). |
| `until` | no | Show commits older than this date. Supports ISO 8601 (e.g., '2024-12-31') or relative formats (e.g., 'yesterday'). |
| `author` | no | Filter commits by author name or email (case-insensitive). |
| `ref` | no | Commit SHA, branch or tag name to list commits of. If not provided, uses the default branch. |
| `page` | no | Page number for pagination (min 1, default: 1). |
| `perPage` | no | Results per page for pagination (min 1, max 100, default: 50). |
### `list_language_models`
Lists the available language models configured on the Sourcebot instance. Use this to discover which models can be specified when calling `ask_codebase`.
Parameters:
This tool takes no parameters.
### `ask_codebase`
Ask a natural language question about the codebase. This tool uses an AI agent to autonomously search code, read files, and find symbol references/definitions to answer your question. Returns a detailed answer in markdown format with code references, plus a link to view the full research session in the Sourcebot web UI.
Parameters:
| Name | Required | Description |
| :-------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `query` | yes | The query to ask about the codebase. |
| `repos` | no | The repositories that are accessible to the agent during the chat. If not provided, all repositories are accessible. |
| `languageModel` | no | The language model to use for answering the question. Object with `provider` and `model`. If not provided, defaults to the first model in the config. Use `list_language_models` to see available options. |
| `visibility` | no | The visibility of the chat session (`'PRIVATE'` or `'PUBLIC'`). Defaults to `PRIVATE` for authenticated users and `PUBLIC` for anonymous users. Set to `PUBLIC` to make the chat viewable by anyone with the link (useful in shared environments like Slack). |
## Environment Variables
| Name | Default | Description |
| :----------------------- | :--------------------------------------------- | :----------------------------------------------- |
| `SOURCEBOT_HOST` | [http://localhost:3000](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. |