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.

Related MCP server: GitHub MCP Server

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)

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

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

Required for the agent (chat / tool picking)

Optional

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)

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.