github-brain

GitHub Brain MCP Server

GitHub Brain is an experimental MCP server for summarizing GitHub discussions, issues, and pull requests. It helps answer questions like:

• What are the contributions of user X in the last month?
• Summarize this month's discussions.

https://github.com/user-attachments/assets/80910025-9d58-4367-af00-bf4c51e6ce86

GitHub Brain complements (but does not replace) the official GitHub MCP server. It uses a local database to store data pulled from GitHub, enabling:

• Fast responses
• More results than the standard 100-item API limit
• Markdown output for token efficiency

As a bonus, GitHub Brain also includes a simple web-based UI for ultra-fast search of discussions, issues, and pull requests.

As a bonus, GitHub Brain also includes a Raycast extension for ultra-fast search of discussions, issues, and pull requests.

GitHub Brain is programmed in Markdown.

Prerequisites

• Go installed

Usage

scripts/run <command> [<args>]

Workflow:

• Populate the local database with the pull command.
• Start the MCP server with the mcp command.

Re-run pull anytime to update the database with new GitHub data. You can do this while mcp is running, but MCP requests may temporarily return errors during the update.

Each command has its own arguments. Some can be set via environment variables. The app will also load environment variables from a .env file in the GitHub Brain's home directory - ~/.github-brain by default. You can change the home directory with the -m argument available for all commands. When executing scripts/run, the home directory is set to the checkout directory.

Example .env file

GITHUB_TOKEN=your_github_token
ORGANIZATION=my-org

pull

Populate the local database with GitHub data.

Example:

scripts/run pull -o my-org

The first call for an organization may take a while. Subsequent calls are faster, updating only with new data.

Argument	Variable	Description
-t	GITHUB_TOKEN	Your GitHub personal token to access the API. Required.
-o	ORGANIZATION	The GitHub organization to pull data from. Required.
-m		GitHub Brain home directory. Default: ~/.github-brain or the repo checkout directory if executed via scripts/run.
-i		Only pull selected entities. Choose from: repositories, discussions, issues, pull-requests. Comma-separated list.
-f		Remove all data before pulling. If combined with -i, only the specified items will be removed.
-e	EXCLUDED_REPOSITORIES	Comma-separated list of repositories to exclude from the pull of discussions, issues, and pull requests. Useful for large repositories that are not relevant to the analysis.

Personal access token scopes

Use the [fine-grained personal access tokens](https://github.com/settings/personal-access-tokens).

For private organizations, the token must have the following configuration:

- Repository permissions: Read access to discussions, issues, metadata, and pull requests. Click [here](https://github.com/settings/personal-access-tokens/new?name=github-brain&description=http%3A%2F%2Fgithub.com%2Fwham%2Fgithub-brain&issues=read&pull_requests=read&discussions=read) to generate.

For public organizations, an empty token is sufficient, as the data is publicly accessible.

mcp

Start the MCP server using the local database.

Example:

scripts/run mcp -o my-org

Argument	Variable	Description
-o	ORGANIZATION	The GitHub organization to work with. Required.
-m		GitHub Brain home directory. Default: ~/.github-brain or the repo checkout directory if executed via scripts/run.

ui

Start the UI server, which provides a web-based interface for interacting with the GitHub data. Alternative to MCP for quick lookups.

Example:

scripts/run ui -o my-org

Argument	Variable	Description
-o	ORGANIZATION	The GitHub organization to work with. Required.
-m		GitHub Brain home directory. Default: ~/.github-brain or the repo checkout directory if executed via scripts/run.
-p	UI_PORT	Port for the UI server. Default: 8080.

Additional Arguments

Version:

github-brain --version

Displays the current version (commit hash and build date).

Installation

scripts/run is a convenience script that runs the MCP server. It builds the Go code and runs the mcp command with the checkout directory as the working directory. As a result, the SQLite database will be created in the db folder of the checkout directory.

Claude

Add to the Claude MCP configuration file:

{
  "mcpServers": {
    "github-brain": {
      "type": "stdio",
      "command": "<path-to-the-checkout-directory>/scripts/run",
      "args": ["mcp"]
    }
}

Where <path-to-the-checkout-directory> is the path to the GitHub Brain repository on your local machine. Merge if mcpServers already exists.

VS Code

Add to the VS Code MCP configuration file:

{
  "servers": {
    "github-brain": {
      "type": "stdio",
      "command": "<path-to-the-checkout-directory>/scripts/run",
      "args": ["mcp"],
      "version": "0.0.1"
    }
  }
}

Where <path-to-the-checkout-directory> is the path to the GitHub Brain repository on your local machine. Merge if servers already exists.

Raycast Extension

Run the Raycast extension with:

scripts/raycast

The extension uses the MCP server to search GitHub data.