🐙 GitHub MCP Agent

A Streamlit application that allows you to explore and analyze GitHub repositories using natural language queries through the Model Context Protocol (MCP).  

This project combines MCP GitHub server with Ollama-powered reasoning, giving you a local-first, AI-driven GitHub analysis assistant.

Output (AI-generated Report):

---

✨ Features

• Natural Language Interface → Ask questions like "What PRs need review?" or "Show repository health metrics."  

• Comprehensive Analysis → Explore issues, pull requests, commits, repository activity, and code quality.  

• Interactive UI → Simple Streamlit interface with query templates and custom input.  

• MCP Integration → Real-time data from GitHub API via the MCP GitHub server.  

• Local Reasoning → Uses Ollama models for summarization & insights (e.g., llama3.1:8b).

---

⚙️ Setup

🔑 Requirements

• Python 3.9+

• Node.js + npm (MCP GitHub server runs with npx)

• Ollama installed locally

• A GitHub Personal Access Token (PAT) → create here

  - Minimum scopes: repo, user

---

📥 Installation

1. Clone this repository

   git clone https://github.com/<your-username>/github-mcp-agent.git

   cd github-mcp-agent

2. Create and activate a virtual environment

python -m venv .venv

3. Activate (Windows)

.venv\Scripts\activate

4. Install dependencies

pip install -r requirements.txt

5. Verify installation

node --version

npm --version

npx --version

6. Install Ollama + pull a reasoning model

ollama pull llama3.1:8b

▶️ Running the App

1. Set your GitHub Token in .env:

env:
GITHUB_TOKEN=your_personal_access_token

2. Run Streamlit

streamlit run app.py

3. In the app:

• Enter your GitHub Token (if not auto-loaded from .env)

• Specify a repository (owner/repo)

• Select a query type or enter a custom one

• Click "🚀 Run Query"

📝 Example Queries

Issues

• Show me issues by label in microsoft/vscode

• What issues are being actively discussed in pytorch/pytorch?

Pull Requests

• What PRs need review in huggingface/transformers?

• Show me recent merged PRs in streamlit/streamlit

Repository

• Show repository health metrics for openai/openai-cookbook

• Analyze code quality trends in numpy/numpy

📂 Project Structure

github-mcp-agent/

│── app.py                 # Streamlit main app

│── requirements.txt

│── .gitignore

│── LICENSE

│── README.md

│── .env                   # GitHub token (not committed)

⚠️ Disclaimer

This project is for educational and experimental purposes only.

It is not affiliated with GitHub, OpenAI, or Ollama.

Always keep your GitHub PAT private and never commit .env.

Built with ❤️ : Azar