Skip to content

github-agent

GitHub MCP Server + A2A Agent for the agent-utilities ecosystem — a typed, deterministic tool surface and supervisor agent over the GitHub REST API.

Official documentation

This site is the canonical reference for github-agent, maintained alongside every release.

PyPI MCP Server License GitHub

Overview

github-agent wraps the GitHub REST API with typed, deterministic MCP tools and a Pydantic-AI supervisor agent. It provides:

  • Api — a requests-based REST client (github_agent.api_client.Api) composed from per-domain mixins (repositories, issues, pull requests, branches, commits, contents, organizations, collaborators, releases, workflows, search), with parallel pagination and tolerant error handling.
  • Action-dispatch MCP tools — eleven tool domains (github_repos, github_issues, github_pulls, …), each toggled by an environment switch and routed by an action argument.
  • An A2A supervisor agent (github-agent console script) that delegates GitHub work to specialized child agents.

The server remains inactive when credentials are absent — a missing GITHUB_TOKEN leaves calls unauthenticated rather than raising at import time.

Explore the documentation

  • Installation — pip, source, extras, and the prebuilt Docker image.
  • Deployment — run the MCP and agent servers, Docker Compose, Caddy + Technitium.
  • Usage — the MCP tools, the Api client, and the CLI.
  • Overview — supervisor architecture and specialized agents.
  • Concepts — the CONCEPT:GH-* registry.

Quick start

pip install github-agent
github-mcp                       # stdio MCP server (default transport)

Connect it to GitHub:

export GITHUB_URL=https://api.github.com
export GITHUB_TOKEN=ghp_your_personal_access_token
github-mcp --transport streamable-http --host 0.0.0.0 --port 8000

See Installation and Deployment for the full matrix (PyPI extras, Docker image, all transports, the agent server, reverse proxy, DNS).