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](https://github.com/github/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 is [programmed in Markdown](https://github.blog/ai-and-ml/generative-ai/spec-driven-development-using-markdown-as-a-programming-language-when-building-with-ai/).
## Installation
```sh
npm i -g github-brain
```
Rerun to update. `sudo` may be required on some systems.
Alternatively use `npx` to run without installing globally and needing `sudo`.
```sh
npx github-brain@latest
```
## Usage
```sh
github-brain
```
Or with `npx`:
```sh
npx github-brain@latest
```
Launches the interactive TUI where you can:
1. **Setup** - Configure authentication and settings
- Login with GitHub (OAuth) - Recommended for most users
- Login with Personal Access Token - For fine-grained tokens or when OAuth is unavailable
- Open configuration file - Edit `.env` directly
2. **Pull** - Populate the local database with GitHub data
Re-run pull anytime to update the database with new GitHub data.
The app loads environment variables from a `.env` file in the GitHub Brain's home directory - `~/.github-brain` by default.
Example .env file
GITHUB_TOKEN=your_github_token
ORGANIZATION=my-org
| Argument | Description |
| :------- | :----------------------------------------- |
| `-m` | Home directory. Default: `~/.github-brain` |
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 Server
Start the MCP server using the local database:
```sh
github-brain mcp
```
Or with `npx`:
```sh
npx github-brain@latest mcp
```
| Argument | Variable | Description |
| :------- | :------------- | :----------------------------------------- |
| `-o` | `ORGANIZATION` | GitHub organization. **Required.** |
| `-m` | | Home directory. Default: `~/.github-brain` |
## MCP Configuration
### Claude
Add to the Claude MCP configuration file:
```json
{
"mcpServers": {
"github-brain": {
"type": "stdio",
"command": "github-brain",
"args": ["mcp"]
}
}
```
Or with `npx`:
```json
{
"mcpServers": {
"github-brain": {
"type": "stdio",
"command": "npx",
"args": ["github-brain@latest", "mcp"]
}
}
```
Merge with existing `mcpServers` if present.
### VS Code
Add to the VS Code MCP configuration file:
```json
{
"servers": {
"github-brain": {
"type": "stdio",
"command": "github-brain",
"args": ["mcp"],
"version": "0.0.1"
}
}
}
```
Or with `npx`:
```json
{
"servers": {
"github-brain": {
"type": "stdio",
"command": "npx",
"args": ["github-brain@latest", "mcp"],
"version": "0.0.1"
}
}
}
```
Merge with existing `servers` if present.
## Development
`scripts/run` builds and runs `github-brain` with the checkout directory as home `-m` (database in `db/`, config in `.env`).