github-brain

GitHub Brain MCP Server

GitHub Brain is an experimental MCP server for summarizing GitHub discussions, issues, and pull requests. 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 stores GitHub data in a local database for:

• Fast responses
• More than the standard 100-item API limit
• Token-efficient Markdown output

GitHub Brain also includes a web-based UI for ultra-fast search:

And a Raycast extension:

GitHub Brain is programmed in Markdown.

Installation

npm i -g github-brain

Or use npx github-brain to run without installing globally.

Usage

github-brain <command> [<args>]

Workflow:

• Use pull to populate the local database
• Use mcp to start the MCP server

Re-run pull anytime to update the database with new GitHub data.

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.

Example .env file

GITHUB_TOKEN=your_github_token
ORGANIZATION=my-org

pull

Populate the local database with GitHub data.

Example:

github-brain pull -o my-org

The first run may take a while. Subsequent runs are faster, fetching only 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		Home directory. Default: ~/.github-brain (or checkout directory if run via scripts/run).
-i		Pull only selected entities: repositories, discussions, issues, pull-requests (comma-separated).
-f		Remove all data before pulling. With -i, removes only specified items.
-e	EXCLUDED_REPOSITORIES	Repositories to exclude (comma-separated). Useful for large repos not relevant to your analysis.

Personal access token scopes

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

**Private organizations:** Token needs read access to discussions, issues, metadata, and pull requests. [Generate token](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).

**Public organizations:** Any token works (data is publicly accessible).

mcp

Start the MCP server using the local database.

Example:

github-brain mcp -o my-org

Argument	Variable	Description
-o	ORGANIZATION	GitHub organization. Required.
-m		Home directory. Default: ~/.github-brain (or checkout directory if run via scripts/run).

ui

Start the web UI for quick searches (alternative to MCP).

github-brain ui -o my-org

Argument	Variable	Description
-o	ORGANIZATION	GitHub organization. Required.
-m		Home directory. Default: ~/.github-brain (or checkout directory if run via scripts/run).
-p	UI_PORT	Port. Default: 8080.

Additional Arguments

Version:

github-brain --version

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

MCP Configuration

Claude

Add to the Claude MCP configuration file:

{
  "mcpServers": {
    "github-brain": {
      "type": "stdio",
      "command": "github-brain",
      "args": ["mcp"]
    }
}

Merge with existing mcpServers if present.

VS Code

Add to the VS Code MCP configuration file:

{
  "servers": {
    "github-brain": {
      "type": "stdio",
      "command": "github-brain",
      "args": ["mcp"],
      "version": "0.0.1"
    }
  }
}

Merge with existing servers if present.

Raycast Extension

Run the Raycast extension with:

scripts/raycast

The extension uses the MCP server to search GitHub data.

Development

scripts/run builds and runs github-brain with the checkout directory as home (database in db/, config in .env).