github-brain

<div align="center"> <img src="logo.svg" alt="GitHub Brain Logo" width="150" height="150"> <h1>GitHub Brain MCP Server</h1> </div> **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. <details> <summary>Example .env file</summary> GITHUB_TOKEN=your_github_token ORGANIZATION=my-org </details> | Argument | Description | | :------- | :----------------------------------------- | | `-m` | Home directory. Default: `~/.github-brain` | <details> <summary>Personal access token scopes</summary> 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). </details> ## 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`).