GitHub MCP Agent

Talk to your GitHub repos, issues, and project boards in plain English from your terminal.

You > list open issues in my raytracer repo
You > set priority of issue #42 to urgent
You > what's in progress on the project board?
You > which issues are assigned to maryam?

---

Install

pip install github-mcp-agent

Or with uv:

uv tool install github-mcp-agent

---

Setup

github-agent setup

Interactive wizard:

1. GitHub token (validated immediately)
2. AI provider — choose one:
   • AWS Bedrock — existing profile, access keys, or SSO
   • Anthropic API — API key from console.anthropic.com
   • OpenAI — API key from platform.openai.com
   • Google Gemini — API key from aistudio.google.com
   • GitHub Copilot — browser OAuth flow, requires a Copilot subscription
   • Local (Ollama) — picks from your installed models, no API key needed
3. Model selection (scrollable menu)
4. Pulls the GitHub MCP Docker image

Config saved to ~/.config/github-mcp-agent/.env.

---

Usage

github-agent            # start the agent
github-agent setup      # full setup wizard
github-agent provider   # switch AI provider and model
github-agent model      # switch model within current provider
github-agent token      # update GitHub token
github-agent config     # edit config file in $EDITOR
github-agent prompt     # customize the system prompt in $EDITOR
github-agent -v         # start with verbose tool output

---

Requirements

Requirement	Notes
Python 3.10+
Docker	Must be running — used for the GitHub MCP server
GitHub token	Scopes: repo, read:org, project — github.com/settings/tokens
Provider credentials	See setup wizard

For AWS Bedrock: enable Claude model access in the Bedrock console under Model access.

For Ollama: install from ollama.com, run ollama serve. Models with good tool-calling support: qwen2.5, llama3.1, mistral.

For GitHub Copilot: requires an active Copilot subscription (student pack, individual, or business).

---

How it works

You (terminal)
    │
    ▼
github-agent (CLI)
    │
    ├── AI model (Bedrock / Anthropic / OpenAI / Gemini / Copilot / Ollama)
    │
    └── GitHub MCP Server (Docker)
            │
            └── GitHub API

Uses the Strands Agents SDK with the GitHub MCP server.

---

Troubleshooting

GITHUB_TOKEN not set — run github-agent setup

Docker not running — start Docker Desktop or sudo systemctl start docker

Bedrock access denied — check IAM permissions and model access in your region

Ollama model not found — run ollama list to confirm the model name, re-run github-agent model

No module named github_mcp_agent — reinstall with pip install github-mcp-agent or uv tool install github-mcp-agent