github-brain

GitHub Brain MCP Server is an experimental server that indexes GitHub discussions, issues, and pull requests into a local database to enable fast, contextual querying. It exposes an MCP interface via a stdio-based workflow, allowing you to run the server and then connect tools like Claude or VS Code extensions to query aggregated GitHub data. Start by authenticating with GitHub (OAuth recommended) or by supplying a Personal Access Token, then populate the local database with the Pull operation to pull data from GitHub. Once the database is populated, you can ask questions such as contributions by a user over a period or summarize discussions across a timeframe. The server stores data under a local home directory (default ~/.github-brain) to enable fast responses and to surpass typical API item limits while producing token-efficient Markdown outputs.

Prerequisites:

• Node.js and npm installed on your system
• Access to a GitHub account and an optional GitHub token with appropriate scopes

Install globally (recommended):

1. Run: npm i -g github-brain
   • This makes the github-brain CLI available system-wide.
2. If needed, update later with the same command.

Alternative (without global install):

1. Run with npx: npx github-brain@latest

Usage after installation:

1. Start the MCP server in interactive mode or as a background task depending on your workflow.
2. Use the mcp command inside the MCP workflow to initialize the server and pull data as described in the README.

Environment preparation:

• Create a .env file in the default home directory (~/.github-brain) to store GITHUB_TOKEN and ORGANIZATION if you prefer not to pass them via env vars.
• Example .env: GITHUB_TOKEN=your_github_token ORGANIZATION=your-org

Notes:

• The server reads environment variables from the home directory by default.
• If you use npx, no global installation is required, but you may need network access for each invocation.

Tips and common issues:

• Ensure you provide a GitHub token with appropriate scopes if working with private data or fine-grained access requirements.
• The local database is stored under the home directory (~/.github-brain) by default; back up or manage this directory if needed.
• When using npx, you can run the mcp command as shown in the README; if you encounter permission prompts, try running with elevated permissions or adjust your shell's permissions.
• If your organization data is large, consider performing multiple incremental pulls to keep the local database up to date.
• For VS Code or Claude integrations, ensure the MCP configuration references the correct command and includes the correct version if you’re pinning a specific release.