# GitHub MCP Agent

Ask natural-language questions about GitHub repositories and get answers backed by live GitHub data. On Cloudflare, a Worker calls **any LLM provider** (Google, OpenAI, DeepSeek, Cloudflare, Groq, or a custom OpenAI-compatible API) with tool calling and implements GitHub tools through the REST API. Locally, you can still run the original Streamlit app that talks to the official GitHub MCP server over Docker.

This is a **standalone packaging** of the GitHub MCP agent from [Shubhamsaboo/awesome-llm-apps](https://github.com/Shubhamsaboo/awesome-llm-apps/tree/main/mcp_ai_agents/github_mcp_agent). The original lives inside a large examples collection; this repository is a self-contained project you can clone, run, and deploy.

## What it does

Point the app at any `owner/repo`, type a question, and get a structured answer backed by live GitHub data — not a generic LLM guess. Typical questions:

- Which issues are labeled as bugs?
- Which pull requests still need review?
- What has merged recently?
- How active is this repository?

The agent formats answers in markdown, including tables and links back to GitHub when they help.

## Features

- **Natural-language queries** over issues, pull requests, repository metadata, files, and search
- **Cloudflare Worker + static chat UI** for hosted use (any LLM provider + GitHub REST)
- **Official GitHub MCP server** (optional local path) via Docker for the original Streamlit app
- **Bring your own LLM key**: Google, OpenAI, DeepSeek, Cloudflare Workers AI, Anthropic, Groq, OpenRouter, Mistral, xAI, Together, or any OpenAI-compatible endpoint
- **Sidebar auth, provider picker, and model field**, query templates, and custom questions
- **Optional `.env` / `.dev.vars` loading** so you can keep keys out of the UI

## Hosted architecture (Cloudflare)

Streamlit and the GitHub MCP Docker image cannot run on Cloudflare Pages/Workers. The hosted app is a Cloudflare-native rebuild of the same product:

```
┌─────────────────┐     POST /api/chat (SSE)      ┌──────────────────┐
│ Static chat UI  │ ────────────────────────────► │ Cloudflare Worker│
│ public/         │                               │ Any LLM + tools  │
└─────────────────┘                               └────────┬─────────┘
                                                           │ GitHub REST
                                                           ▼
                                                  ┌──────────────────┐
                                                  │ api.github.com   │
                                                  └──────────────────┘
```

1. The Worker serves the chat UI from `public/` and handles `/api/*`.
2. Chat requests call your chosen LLM with GitHub tools equivalent to the MCP `repos`, `issues`, and `pull_requests` toolsets (plus files and search).
3. The Worker executes those tools against the GitHub REST API using `GITHUB_TOKEN`.
4. Tokens can come from Wrangler secrets or from the sidebar (`X-LLM-Key`, `X-GitHub-Token`). Sidebar values override secrets for that request.

## Deploy on Cloudflare

### Prerequisites

- Node.js 18+
- A Cloudflare account
- An LLM API key from **any** provider (Google, OpenAI, DeepSeek, Cloudflare, Groq, …)
- GitHub personal access token (not committed)

```powershell
git clone https://github.com/MadanMohan0537/github-mcp-agent.git
cd github-mcp-agent
npm install
npx wrangler login
npx wrangler secret put LLM_API_KEY
npx wrangler secret put GITHUB_TOKEN
npx wrangler secret put LLM_PROVIDER
npm run deploy
```

After deploy, Wrangler prints a `*.workers.dev` URL. The UI and API are same-origin.

### Local Cloudflare development

```powershell
copy .dev.vars.example .dev.vars
```

Edit `.dev.vars` with real keys (never commit it), then:

```powershell
npm run dev
```

Open the URL Wrangler prints (usually `http://127.0.0.1:8787`).

| Variable | Required | Purpose |
| --- | --- | --- |
| `LLM_API_KEY` | Yes (for queries) | Any provider key: Google, OpenAI, DeepSeek, Groq, Cloudflare, etc. |
| `LLM_PROVIDER` | No | `openai`, `google`, `deepseek`, `cloudflare`, `anthropic`, `groq`, `openrouter`, `mistral`, `xai`, `together`, or `custom` |
| `LLM_MODEL` | No | Model id for that provider |
| `LLM_BASE_URL` | Custom / Cloudflare override | OpenAI-compatible base URL |
| `CLOUDFLARE_ACCOUNT_ID` | Cloudflare Workers AI | Account id used to build the Workers AI URL |
| `GITHUB_TOKEN` | Yes (for queries) | Authenticates GitHub REST calls |
| Provider aliases | No | `GOOGLE_API_KEY`, `OPENAI_API_KEY`, `DEEPSEEK_API_KEY`, `GROQ_API_KEY`, … |

You can also type keys into the sidebar. The field is labeled **LLM API key**, not OpenAI-only. Sidebar values are sent only to this Worker as request headers.

Token scopes:

- Public repositories: `public_repo` is enough
- Private repositories: `repo`

## Optional local path: Streamlit + GitHub MCP Docker

The original Python app is unchanged. It uses Agno, Streamlit, and `ghcr.io/github/github-mcp-server`.

```
┌─────────────────┐     natural-language query      ┌──────────────────┐
│  Streamlit UI   │ ───────────────────────────────► │  Agno Agent      │
│  github_agent.py│                                  │  (any LLM)      │
└─────────────────┘                                  └────────┬─────────┘
                                                              │ MCP tools
                                                              ▼
                                                     ┌──────────────────┐
                                                     │ Docker container │
                                                     │ github-mcp-server│
                                                     └────────┬─────────┘
                                                              │ GitHub API
                                                              ▼
                                                     ┌──────────────────┐
                                                     │ api.github.com   │
                                                     └──────────────────┘
```

### Prerequisites

| Requirement | Notes |
| --- | --- |
| Python 3.10+ | Developed against 3.12 |
| [Docker](https://www.docker.com/get-started) | Must be running; the GitHub MCP server is a container |
| LLM API key | Google, OpenAI, DeepSeek, Cloudflare, Groq, or any OpenAI-compatible provider |
| GitHub personal access token | From [github.com/settings/tokens](https://github.com/settings/tokens) |

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
copy .env.example .env
streamlit run github_agent.py
```

Or `.\run.ps1` / `run.bat` after the venv is installed. Open the URL Streamlit prints (usually `http://localhost:8501`).

First Docker pull of `ghcr.io/github/github-mcp-server` can take a minute. Queries time out after 120 seconds.

## Example usage

Repository: `Shubhamsaboo/awesome-llm-apps`

**Issues**

- `Find issues labeled as bugs in Shubhamsaboo/awesome-llm-apps`
- `What issues are being actively discussed?`

**Pull requests**

- `What PRs need review?`
- `Show me recent merged PRs`

**Repository**

- `Show repository health metrics`
- `Show repository activity patterns`
- `Analyze code quality trends`

Keep each question focused on one area (issues, PRs, or repo stats). Broad prompts take longer and produce noisier answers.

## Project layout

```
github-mcp-agent/
├── public/              # Cloudflare static chat UI
├── src/                 # Worker: multi-provider LLM agent + GitHub REST tools
├── wrangler.toml        # Workers + assets project
├── package.json         # npm run dev / npm run deploy
├── github_agent.py      # Optional local Streamlit + MCP Docker app
├── requirements.txt
├── .env.example
├── .dev.vars.example
├── LICENSE              # Apache License 2.0 (from the original project)
├── NOTICE
└── README.md
```

## Troubleshooting

| Symptom | What to check |
| --- | --- |
| `LLM API key not provided` | Sidebar key, `.dev.vars`, or `npx wrangler secret put LLM_API_KEY` |
| `GitHub token not provided` | Sidebar token, `.dev.vars`, or `npx wrangler secret put GITHUB_TOKEN` |
| Worker deploy asks you to log in | Run `npx wrangler login` and complete the browser OAuth flow |
| Docker errors / `docker` not found | Only needed for the Streamlit path; install Docker and start the daemon |
| Timeout / truncated answers | Narrow the query; hosted tool results are clipped to keep Worker/LLM limits |
| `ImportError` about `McpError` / `mcp` | Streamlit path: install from this repo’s `requirements.txt` (`mcp>=1.9,<2.0`) |
| 401 / permission errors from GitHub | Token expired, or missing `repo` / `public_repo` scope |

## Attribution

Based on **GitHub MCP Agent** in [Shubhamsaboo/awesome-llm-apps](https://github.com/Shubhamsaboo/awesome-llm-apps), specifically:

[mcp_ai_agents/github_mcp_agent](https://github.com/Shubhamsaboo/awesome-llm-apps/tree/main/mcp_ai_agents/github_mcp_agent)

Upstream tutorial: [Build an MCP GitHub agent in less than 50 lines of code](https://www.theunwindai.com/p/build-an-mcp-github-agent-in-less-than-50-lines-of-code).

This repository is an independent standalone checkout with documentation, a Cloudflare Workers host, and small packaging changes. It is not an official GitHub or Cloudflare product.

## License

The original awesome-llm-apps project is licensed under the [Apache License 2.0](LICENSE). This derivative keeps that license. See [NOTICE](NOTICE) for source attribution.