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. 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)

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

copy .dev.vars.example .dev.vars

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

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	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

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, specifically:

mcp_ai_agents/github_mcp_agent

Upstream tutorial: 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. This derivative keeps that license. See NOTICE for source attribution.