GitHub MCP Project

This is a learning project built in two parts:

1. A GitHub MCP server — a program that knows how to talk to GitHub (list your repos, read issues, create issues, and so on).
2. An MCP client — a chatbot that connects to that server and lets you ask for things in plain English, like "which of my repos have open issues?" The chatbot figures out on its own which GitHub action to run.

What is MCP?

MCP stands for Model Context Protocol. It's a standard way for an AI chatbot to talk to a separate program that knows how to do things (like call GitHub's API). Instead of teaching the chatbot everything about GitHub directly, we built a small server that knows GitHub, and a client that connects an AI model (in this project, Groq) to that server. The AI decides what to do; the server actually does it.

Think of it like this: the server is a toolbox, and the client is a person who's smart enough to pick the right tool for the job, without you having to tell them exactly which tool to use.

What can it do?

Read things (safe, no confirmation needed):

• List your repositories
• Get details about a specific repository
• List issues on a repository
• Get full details of one issue
• List pull requests on a repository
• Search for issues across all your repositories at once
• Read a repository's README

Change things on GitHub (asks you to confirm first):

• Create a new issue
• Add a comment to an issue
• Close or reopen an issue
• Edit an issue's title/body
• Create a brand-new repository

Other:

• Turn a plain-language bug description into a well-structured GitHub issue draft (title + Steps to Reproduce / Expected Behavior / Actual Behavior)

Anything that actually changes something on GitHub always shows you a confirmation box first and waits for you to click Approve or Decline — nothing happens on your real GitHub account without your say-so.

Project layout

src/
  github_mcp/         # Phase 1: the server that knows how to talk to GitHub
    server.py         # Defines every tool/resource/prompt
    github_client.py  # Handles GitHub login and shared error handling
  mcp_client/         # Phase 2: the chatbot that connects to the server
    client.py         # Run this for a terminal-based chat
    web.py            # Run this for a browser-based chat
    groq_llm.py        # The logic that lets the AI decide what to do
    guard.py           # Safety check before any "changes something" action runs
.env                  # Your secret keys (never share this file)
requirements.txt       # The list of Python packages this project needs

Setup

1. Make sure the virtual environment is set up (it already is, in .venv).
2. Add two secret keys to a .env file in the project folder:

   GITHUB_TOKEN=your_github_personal_access_token
   GROQ_API_KEY=your_groq_api_key
   

   • GITHUB_TOKEN: a GitHub personal access token. For it to be able to do everything above (including creating repositories), use a classic token with the repo scope, from github.com/settings/tokens.
   • GROQ_API_KEY: a free API key from console.groq.com — this is what powers the AI's decision-making.

Running it

Option A — Chat in your browser (recommended):

./.venv/Scripts/python.exe src/mcp_client/web.py

Then open http://127.0.0.1:8000 in your browser and start typing questions.

Option B — Chat in the terminal:

./.venv/Scripts/python.exe src/mcp_client/client.py

Type your question when prompted; type exit or quit to stop.

Both options talk to the exact same server and understand the exact same questions — the only difference is where you type and read the conversation.

Example questions to try

• "List my repositories"
• "Which of my repositories have open issues?"
• "What is the [some-repo] repo built with, based on its README?"
• "Create an issue on [owner/repo] titled 'Sample issue' with body 'testing'"
• "Close issue #1 on [owner/repo]"
• "Draft a GitHub issue for this bug: the login button doesn't respond when clicked"

Where to read more

This README covers the basics. The full, detailed step-by-step story of how this project was built — every decision, every bug found and fixed, and why — is recorded in two files:

• .claude/agents/doc-writer.md — the server's build history
• .claude/agents/client-doc-writer.md — the client's build history