github-mcp

Thin FastMCP server exposing flat GitHub tools (issues, PRs, code browsing) over the GitHub REST API. Built for local LLM clients: scalar arguments, comma-separated lists instead of JSON arrays, trimmed JSON-string responses, and failures isolated as {"error": ...}.

Why not the official github/github-mcp-server? Its default toolset alone registers 46 tools (~10-15k tokens of schema) with rich nested arguments, and self-hosted it is stdio-only. This server keeps 15 flat tools (~2-3k tokens) and speaks streamable HTTP natively, which Open WebUI consumes directly. OpenCode terminal sessions continue to use the gh CLI.

Tools

repo arguments are always "owner/repo".

Auth

One fine-grained PAT in the environment (GITHUB_PERSONAL_ACCESS_TOKEN): Issues r/w, Pull requests r/w, Contents r (also covers releases), Checks r (CI summary in get_pull_request; without it the summary degrades to a checks_error hint), Metadata r (auto-granted). Actions r is not needed today, only if workflow-run tools are added later. A local .env file is loaded if present.

Run

# stdio (default, local MCP clients)
GITHUB_PERSONAL_ACCESS_TOKEN=... uv run github-mcp

# streamable-http (Docker does this via MCP_TRANSPORT=http)
MCP_TRANSPORT=http MCP_PORT=3102 uv run github-mcp
curl -s http://localhost:3102/mcp   # -> 406 (streamable-http requires MCP headers)

Docker image: ghcr.io/awernick/github-mcp:main, published on every push to main. Deployed on robusto by awernick/picolino-config (robusto/github-mcp/, port 3102); Open WebUI registers it as an external tool server (Type: MCP Streamable HTTP) at http://github-mcp:3102/mcp.

Development

uv sync --dev          # or: pip install -e ".[dev]"
uv run pytest
uv run ruff check .