sourcebot/packages/mcp/README.md

Sourcebot MCP - Fetch code context from GitHub, GitLab, Bitbucket, and more

The Sourcebot MCP server gives your LLM agents the ability to fetch code context across thousands of repos hosted on GitHub, GitLab, BitBucket and more. Ask your LLM a question, and the Sourcebot MCP server will fetch relevant context from its index and inject it into your chat session. Some use cases this unlocks include:

• Enriching responses to user requests:

  • "What repositories are using internal library X?"
  • "Provide usage examples of the CodeMirror component"
  • "Where is the useCodeMirrorTheme hook defined?"
  • "Find all usages of deprecatedApi across all repos"

• Improving reasoning ability for existing horizontal agents like AI code review, docs generation, etc.

  • "Find the definitions for all functions in this diff"
  • "Document what systems depend on this class"

• Building custom LLM horizontal agents like like compliance auditing agents, migration agents, etc.

  • "Find all instances of hardcoded credentials"
  • "Identify repositories that depend on this deprecated api"

Getting Started

1. Install Node.JS >= v18.0.0.

2. (optional) Spin up a Sourcebot instance by following this guide. The host url of your instance (e.g., http://localhost:3000) is passed to the MCP server via the SOURCEBOT_HOST url. This allows you to control which repos Sourcebot MCP fetches context from (including private repos).

   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. Add additional repositories by opening a PR.

3. Install @sourcebot/mcp into your MCP client:

   Cursor

   Cursor MCP docs

   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:

   {
       "mcpServers": {
           "sourcebot": {
               "command": "npx",
               "args": ["-y", "@sourcebot/mcp@latest" ],
               // Optional - if not specified, https://demo.sourcebot.dev is used
               "env": {
                   "SOURCEBOT_HOST": "http://localhost:3000"
               }
           }
       }
   }
   

   Windsurf

   Windsurf MCP docs

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

   Paste the following into your mcp_config.json file:

   {
       "mcpServers": {
           "sourcebot": {
               "command": "npx",
               "args": ["-y", "@sourcebot/mcp@latest" ],
               // Optional - if not specified, https://demo.sourcebot.dev is used
               "env": {
                   "SOURCEBOT_HOST": "http://localhost:3000"
               }
           }
       }
   }
   

   VS Code

   VS Code MCP docs

   Add the following to your .vscode/mcp.json file:

   {
       "servers": {
           "sourcebot": {
               "type": "stdio",
               "command": "npx",
               "args": ["-y", "@sourcebot/mcp@latest"],
               // Optional - if not specified, https://demo.sourcebot.dev is used
               "env": {
                   "SOURCEBOT_HOST": "http://localhost:3000"
               }
           }
       }
   }
   

   Claude Code

   Claude Code MCP docs

   Run the following command:

   # SOURCEBOT_HOST env var is optional - if not specified,
   # https://demo.sourcebot.dev is used.
   claude mcp add sourcebot -e SOURCEBOT_HOST=http://localhost:3000 -- npx -y @sourcebot/mcp@latest
   

   Claude Desktop

   Claude Desktop MCP docs

   Add the following to your claude_desktop_config.json:

   {
       "mcpServers": {
           "sourcebot": {
               "command": "npx",
               "args": ["-y", "@sourcebot/mcp@latest"],
               // Optional - if not specified, https://demo.sourcebot.dev is used
               "env": {
                   "SOURCEBOT_HOST": "http://localhost:3000"
               }
           }
       }
   }
   

   
   

   Alternatively, you can install using via Smithery. For example:

   npx -y @smithery/cli install @sourcebot-dev/sourcebot --client claude
   

4. Tell your LLM to use sourcebot when prompting.

For a more detailed guide, checkout the docs.

Available Tools

search_code

Fetches code that matches the provided regex pattern in query.

Temporal Filtering: Use since and until to filter by repository index time (when Sourcebot last indexed the repo). This is different from commit time. See search_commits for commit-time filtering.

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).
gitRevision	no	Git revision to search (e.g., 'main', 'develop', 'v1.0.0'). Defaults to HEAD.
since	no	Only search repos indexed after this date. Supports ISO 8601 or relative (e.g., "30 days ago").
until	no	Only search repos indexed before this date. Supports ISO 8601 or relative (e.g., "yesterday").
maxTokens	no	Max tokens to return (default: env.DEFAULT_MINIMUM_TOKENS).

list_repos

Lists repositories indexed by Sourcebot with optional filtering and pagination.

Temporal Filtering: Use activeAfter and activeBefore to filter by repository index time (when Sourcebot last indexed the repo). This is the same filtering behavior as search_code's since/until parameters.

Parameters

Name	Required	Description
query	no	Filter repositories by name (case-insensitive).
pageNumber	no	Page number (1-indexed, default: 1).
limit	no	Number of repositories per page (default: 50).
activeAfter	no	Only return repos indexed after this date. Supports ISO 8601 or relative (e.g., "30 days ago").
activeBefore	no	Only return repos indexed before this date. Supports ISO 8601 or relative (e.g., "yesterday").

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.

search_commits

Searches for commits in a specific repository based on actual commit time (NOT index time).

Requirements: Repository must be cloned on the Sourcebot server disk. Sourcebot automatically clones repositories during indexing, but the cloning process may not be finished when this query is executed. Use list_repos first to get the repository ID.

Date Formats: Supports ISO 8601 dates (e.g., "2024-01-01") and relative formats (e.g., "30 days ago", "last week", "yesterday").

Parameters

Name	Required	Description
repoId	yes	Repository identifier: either numeric database ID (e.g., 123) or full repository name (e.g., "github.com/owner/repo") as returned by list_repos.
query	no	Search query to filter commits by message (case-insensitive).
since	no	Show commits after this date (by commit time). Supports ISO 8601 or relative formats.
until	no	Show commits before this date (by commit time). Supports ISO 8601 or relative formats.
author	no	Filter by author name or email (supports partial matches).
maxCount	no	Maximum number of commits to return (default: 50).

Date Format Examples

All temporal parameters support:

• ISO 8601: "2024-01-01", "2024-12-31T23:59:59Z"
• Relative dates: "30 days ago", "1 week ago", "last month", "yesterday"

Important: Different tools filter by different time dimensions:

• search_code since/until: Filters by index time (when Sourcebot indexed the repo)
• list_repos activeAfter/activeBefore: Filters by index time (when Sourcebot indexed the repo)
• search_commits since/until: Filters by commit time (actual git commit dates)

Supported Code Hosts

Sourcebot supports the following code hosts:

• GitHub
• GitLab
• Bitbucket Cloud
• Bitbucket Data Center
• Gitea
• Gerrit

| Don't see your code host? Open a feature request.

Future Work

Semantic Search

Currently, Sourcebot only supports regex-based code search (powered by zoekt under the hood). It is great for scenarios when the agent is searching for is something that is super precise and well-represented in the source code (e.g., a specific function name, a error string, etc.). It is not-so-great for fuzzy searches where the objective is to find some loosely defined category or concept in the code (e.g., find code that verifies JWT tokens). The LLM can approximate this by crafting regex searches that attempt to capture a concept (e.g., it might try a query like "jwt|token|(verify|validate).*(jwt|token)"), but often yields sub-optimal search results that aren't related. Tools like Cursor solve this with embedding models to capture the semantic meaning of code, allowing for LLMs to search using natural language. We would like to extend Sourcebot to support semantic search and expose this capability over MCP as a tool (e.g., semantic_search_code tool). GitHub Discussion