GitHub MCP Server

A project that lets an AI assistant talk to GitHub using safe, structured tools.

In plain words: instead of the AI guessing how GitHub works, this project gives it a clear menu of actions — like “list my repos”, “show open issues”, or “read a file”. The AI picks the right action, this server talks to GitHub, and the answer comes back in a clean format the AI can understand.

---

What problem does this solve?

Chatbots are good at language, but they do not automatically have live access to your GitHub account.

This project builds a bridge:

1. You ask something in normal English (“Show open issues in microsoft/vscode”).
2. An AI model (via Groq) decides which GitHub tool to use.
3. The MCP server runs that tool against the real GitHub API.
4. Results are cleaned up (normalized) and returned to the AI.
5. The AI explains the result to you in simple language.

MCP means Model Context Protocol. Think of it as a standard plug: any compatible AI client can connect to this server and use its tools.

---

Big picture (architecture)

You
  ↓
AI Agent (client/agent.py)  ← talks to Groq LLM
  ↓
MCP Server (notebooks/server.py)  ← menu of GitHub tools
  ↓
GitHub Client  ← HTTP calls with your token
  ↓
GitHub REST API
  ↓
GitHub

Design rule (important)

Tools stay thin:

1. Check the input (is the repo name valid?).
2. Call the GitHub client.
3. Normalize the response into a stable shape.
4. Return that clean data to the agent.

All messy GitHub details stay inside the client layer — not scattered across tools.

---

Project folders (what each part is for)

Path	What it is
notebooks/server.py	Main MCP server — the production entrypoint the agent starts
notebooks/schemas.py	Stable data shapes (Pydantic models) for agents
notebooks/normalize.py	Converts raw GitHub JSON → those stable shapes
notebooks/safety.py	Confirm / dry-run / allowlist for dangerous tools
notebooks/pagination.py	Page helpers for list tools (page, has_next, …)
notebooks/logging_utils.py	JSON logs to stderr (never prints secrets)
notebooks/server_1.py	Older/experimental copy — prefer server.py
notebooks/01_github_mcp_server.ipynb	Learning notebook (how the server was built step by step)
client/agent.py	Chat agent that connects to the MCP server over stdio
client/test_tool_picking.py	Checks whether the AI picks the right tool for sample prompts
.env	Your private keys (never commit this)
.env.example	Template showing which keys you need
requirements.txt	Python packages to install
SETUP.md	Step-by-step setup for non-technical users

---

What you can do with the tools

The server exposes many GitHub actions. Grouped simply:

Read (safe to explore)

• List your repositories
• Get repo details
• List / get issues and pull requests
• Get PR diffs
• List branches, commits, labels
• Search code in a repo
• Read file contents
• List GitHub Actions workflow runs

Write (changes GitHub)

• Create issues, comments, PRs, branches, labels
• Update issues, add/remove labels
• Reopen issues

Destructive (can hurt things — protected)

These need extra confirmation by default:

• merge_pull_request
• delete_file
• create_repository
• create_or_update_file
• close_issue

For these, the agent should usually:

1. Call with dry_run=true → preview only
2. Call again with confirm=true → actually do it

You can tighten or loosen this with environment settings (see below).

---

Normalized responses (why agents like this)

Raw GitHub responses are huge and change often. This project returns stable shapes.

List tools always look like:

{
  "count": 20,
  "items": [ ... ],
  "page": 1,
  "per_page": 20,
  "has_next": true,
  "has_prev": false,
  "next_page": 2,
  "prev_page": null,
  "last_page": 5
}

To get the next page, call the same tool again with page=2 (or page=next_page).

Issue example:

{
  "number": 42,
  "title": "Bug in login",
  "state": "open",
  "author": "some-user",
  "labels": ["bug"],
  "comments": 3,
  "html_url": "https://github.com/...",
  "is_pull_request": false
}

Also: get_issues filters out pull requests (GitHub’s issues API mixes them in).

---

Safety features

Feature	Meaning
confirm=true	Required to run destructive tools (default mode)
dry_run=true	Shows what would happen; does not change GitHub
destructiveHint	MCP annotation so clients know a tool is risky
Allowlist	Optional list of which destructive tools are even allowed
Mode	confirm (default), allow (no confirm), or deny (block all)

Environment variables (optional):

GITHUB_MCP_DESTRUCTIVE_MODE=confirm
GITHUB_MCP_DESTRUCTIVE_ALLOWLIST=merge_pull_request,delete_file

---

Logging (for debugging)

The server writes JSON logs to stderr only.

Why stderr? MCP uses stdout for the protocol. If we printed logs there, the AI connection would break.

Logs include things like:

• request method and path
• HTTP status
• duration
• rate-limit remaining

They never log:

• your GitHub token
• Authorization headers
• secret-looking values (PATs, bearer tokens, etc.)

Example log line:

{"ts":"2026-08-23T12:00:00+00:00","level":"INFO","event":"github_request","method":"GET","path":"/repos/microsoft/vscode/issues","status_code":200,"duration_ms":120.5}

---

The AI agent (client/agent.py)

The agent:

1. Starts the MCP server as a subprocess (notebooks/server.py).
2. Asks the server for the tool list.
3. Sends your question + tools to Groq.
4. If Groq wants a tool, the agent calls it through MCP.
5. Sends the tool result back to Groq for a final answer.

Useful commands (from the project folder, with the virtual environment active):

# See all registered tools
python client/agent.py --list-tools

# Only show which tool the AI would pick (no GitHub write)
python client/agent.py --dry-run "list my github repos"

# One real question, then exit
python client/agent.py --once "show open issues for microsoft/vscode"

# Interactive chat
python client/agent.py

# Check tool-picking quality on many sample prompts
python client/test_tool_picking.py

Loop limits (optional):

python client/agent.py --max-rounds 5 --once "..."

Or in .env:

AGENT_MAX_TOOL_ROUNDS=8
AGENT_MAX_TOOL_CALLS=16
AGENT_MAX_CONSECUTIVE_ERRORS=3

---

Environment variables

Required for the MCP server

Variable	Purpose
GITHUB_TOKEN	Personal access token so the server can call GitHub
GITHUB_USERNAME	Your GitHub username (used at startup validation)
GITHUB_REPO	A default repo name (used at startup validation)

Required for the agent (chat / tool picking)

Variable	Purpose
GROQ_API_KEY	API key for Groq (LLM)

Optional

Variable	Purpose
GROQ_MODEL	Default: openai/gpt-oss-20b
GITHUB_MCP_DESTRUCTIVE_MODE	confirm / allow / deny
GITHUB_MCP_DESTRUCTIVE_ALLOWLIST	Comma-separated destructive tool names
AGENT_MAX_TOOL_ROUNDS	Max tool rounds per user message
AGENT_MAX_TOOL_CALLS	Max tool executions per user message
AGENT_MAX_CONSECUTIVE_ERRORS	Stop after N tool failures in a row

Copy .env.example → .env and fill in real values. See SETUP.md for the full walkthrough.

---

Tech stack (for the curious)

• Python 3.13+ (project was developed on 3.13)
• MCP (mcp Python package) — tool server protocol
• httpx — HTTP client for GitHub
• Pydantic — schemas / validation
• python-dotenv — load .env
• OpenAI-compatible client → Groq for the agent
• Jupyter (optional) — the learning notebook

---

How to set up and run

Follow the friendly guide:

👉 SETUP.md — install Python, create keys, configure .env, and run your first commands.

Short version (if you already know Python):

cd "path\to\Github-MCP-server"
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
copy .env.example .env
# edit .env with your tokens
python client/agent.py --list-tools
python client/agent.py --once "list my github repos"

---

Learning path (recommended)

1. Read this README (you are here).
2. Complete SETUP.md until --list-tools works.
3. Read docs/ARCHITECTURE_HLD_LLD.md for HLD + LLD flows.
4. Try --dry-run and --once with simple read-only questions.
5. Run the 50-scenario manual test plan: tests/MANUAL_TESTING_50_SCENARIOS.md
   • Auto picking: python client/run_manual_scenarios.py
6. Open notebooks/01_github_mcp_server.ipynb to see how each layer was built.
7. Only then try write/destructive tools with dry_run + confirm.

---

Troubleshooting (quick)

Problem	Likely fix
No module named 'mcp'	Activate .venv or use .\.venv\Scripts\python.exe
Groq model 404	Set GROQ_MODEL=openai/gpt-oss-20b (or another model from your Groq account)
Missing env vars	Fill GITHUB_TOKEN, GITHUB_USERNAME, GITHUB_REPO in .env
Destructive tool blocked	Expected — use dry_run=true then confirm=true, or set mode in .env
Agent hangs on exit (Windows)	Known stdio quirk; one-shot commands force-exit after finishing

---

Security reminders

• Never commit .env.
• Never paste your GitHub or Groq tokens into chat, screenshots, or GitHub issues.
• Prefer a GitHub token with only the scopes you need.
• Keep GITHUB_MCP_DESTRUCTIVE_MODE=confirm (or deny) unless you fully trust the environment.
• Do not share server_1.py debug output if it ever printed tokens in older experiments — use server.py.

---

License / ownership

This is a personal / learning Gen-AI project for a GitHub MCP server and agent. Adjust ownership and license as needed before publishing publicly.