MCP GitHub CrunchTools

A secure MCP (Model Context Protocol) server for GitHub issues, pull requests, Actions runs, releases, repository files, and search. Works with github.com and GitHub Enterprise Server.

Overview

This MCP server is designed to be:

• Secure by default - STRIDE threat model (see SECURITY.md), Pydantic input validation, and the API token held as a SecretStr to prevent accidental logging

• No third-party services - Runs locally via stdio, your API token never leaves your machine

• Multi-instance - Works with github.com or GitHub Enterprise Server via configurable API URL

• Cross-platform - Works on Linux, macOS, and Windows

• Automatically updated - GitHub Actions monitor for CVEs and update dependencies

• Containerized - Available at quay.io/crunchtools/mcp-github built on Hummingbird Python base image

Related MCP server: GitHub Prod MCP

Naming Convention

Why Hummingbird?

The container image is built on the Hummingbird Python base image from Project Hummingbird, which provides:

• Minimal CVE exposure - Built with a minimal package set, dramatically reducing the attack surface

• Regular updates - Security patches are applied promptly

• Optimized for Python - Pre-configured Python environment

• Production-ready - Proper signal handling and non-root user defaults

Features

26 tools. Tools marked write change something on GitHub; the others only read and publish readOnlyHint. The last column is the fine-grained token permission the tool needs (see Token permissions).

Issues (5 tools)

Pull Requests (9 tools)

Actions (6 tools)

Releases (1 tool)

Files (2 tools)

Search (2 tools)

Limits on what a tool returns

• list_pull_request_comments_tool reads each of its three kinds oldest first, up to 300 items per kind. truncated and truncated_kinds say when newer items were left out. Called on a plain issue it says so; use list_issue_comments_tool there.

• list_issue_comments_tool returns one page (up to 100 comments); follow pagination.next_page for more.

• get_workflow_run_tool lists up to 300 jobs; jobs_truncated says when the run has more.

• get_failed_job_logs_tool returns a failure_summary per job by default — the tail lines that name the cause (error annotations, test failures, tracebacks, non-zero exits) — scanning at most 1000 lines per job (200 by default), for at most 5 failed jobs, and at most 256 KiB of log text in all, split evenly between the jobs. Pass include_raw_log=true to also get the full cleaned tail as log/log_lines; a scanning gateway may withhold that raw tail where it delivers the summary. tail_lines in the result is the value actually used, failed_jobs_omitted counts the jobs left out, and truncated is set on a job whose log or summary was cut and on the result when anything was. Only the first 300 jobs of a run are examined; jobs_truncated says when the run has more, and the counts then cover only those.

Installation

With uvx (Recommended)

uvx mcp-github-crunchtools

With pip

pip install mcp-github-crunchtools

With Container

podman run -e GITHUB_TOKEN=your_token \
    quay.io/crunchtools/mcp-github

Configuration

Environment Variables

Per-request token

GitHub's own hosted MCP server takes the caller's token on every HTTP request as Authorization: Bearer <token> and acts with it. With GITHUB_ACCEPT_REQUEST_TOKEN=true this server does the same, so a client configured for GitHub's server can point here instead with the same header.

• Over the streamable-http or sse transport, a request carrying Authorization: Bearer <token> is sent to GitHub with that token, for that request only. Concurrent requests with different tokens each use their own; the token is never stored on the shared client.

• A request without the header falls back to GITHUB_TOKEN. With the option on, GITHUB_TOKEN is optional: an instance without it serves only requests that bring a token, and refuses the others before calling GitHub ("No GitHub token for this request").

• The header must be exactly Bearer <token> (scheme in any case, one space, a token of printable ASCII with no spaces). Anything else is refused, never forwarded, even when GITHUB_TOKEN is set.

• The request token is scrubbed from error messages like GITHUB_TOKEN is.

• With the option off (the default) an incoming Authorization header is ignored, exactly as before. stdio has no request headers and always uses GITHUB_TOKEN.

The option makes the server act as whoever sends a token. Expose the HTTP port only to callers you would hand that token to anyway, behind TLS.

Creating a GitHub Personal Access Token

1. Navigate to token settings

   • Go to https://github.com/settings/tokens

2. Create a token

   • Name: mcp-github-crunchtools

   • Expiration: Set an appropriate date (90 days recommended)

   • Scopes: Grant only what the tools you use need; see Token permissions.

3. Copy and Store Token

   • Copy the token immediately (shown only once)

   • Store securely in a password manager

Token permissions

For a fine-grained personal access token, the repository permissions are:

get_pull_request_checks_tool and merge_pull_request_tool read check-runs, and GitHub's permission table for fine-grained tokens has no permission for that endpoint: a fine-grained token gets 403 on a private repository. Both tools then read the head commit's GitHub Actions jobs instead (Actions: read). Every Actions job is a check run with the same id and name, so the verdict and the merge gate are the same for checks GitHub Actions reports. Checks from any other app are not visible that way, so the merge gate refuses a required check that names another app, or that accepts any app and has no commit status, as missing. checks_source in each result says which was read, and the checks verdict then carries a note saying other apps' checks are not visible. Only the newest run of each workflow and event is read, and a commit with runs of more than 30 workflows is not judged.

The search tools have no permission of their own: they return what the token can already read.

Three things worth knowing before granting write:

• Contents: write is the merge and release permission. GitHub has no narrower one: the same grant lets the token push commits and tags. A release published with create_release_tool also fires the repository's on: release workflows.

• A release whose target commit changes a workflow file under .github/workflows/, relative to the default branch, additionally needs Workflows: write; without it GitHub answers 404. Expect the same of a merge that brings workflow changes in.

• The merge gate checks required status checks itself, below. Other branch rules (required reviews, for instance) are left to GitHub, which answers 405 when it refuses; a token that may bypass the rules gets past them.

The merge gate

An organization owner, or anyone on a ruleset's bypass list, can merge past failing required checks: GitHub merges a red pull request for such a token. So merge_pull_request_tool does not leave the checks to GitHub. Before it merges it:

1. reads the pull request's base branch and head SHA, and refuses if sha was given and the head has moved;

2. collects the base branch's required status checks from its active rulesets and its classic branch protection, read from the branch itself so no Administration permission is needed. An error reading either, or a protected branch whose protection is not shown, refuses the merge rather than count as none;

3. refuses if no check is required, unless allow_no_required_checks=True;

4. requires, for every required check on the head commit, a completed check run of that name concluding success, skipped or neutral (the most recent run of the name decides), or a commit status of success. A rule that names an app accepts only that app's check runs. A token that cannot read check-runs is judged on the Actions jobs (see above). A missing, pending or failed check refuses the merge, and the error lists each one and why;

5. reads the pull request again and refuses if its head or base changed meanwhile (GitHub's merge call pins the head but not the base), then merges with the head SHA pinned, so a later push makes GitHub refuse (409) rather than merge code nobody checked.

With a classic token, repo covers all of the above (public_repo for public repositories only), plus workflow for the workflow-file case.

Add to Claude Code

claude mcp add mcp-github-crunchtools \
    --env GITHUB_TOKEN=your_token_here \
    -- uvx mcp-github-crunchtools

For GitHub Enterprise Server:

claude mcp add mcp-github-crunchtools \
    --env GITHUB_TOKEN=your_token_here \
    --env GITHUB_API_URL=https://ghe.example.com/api/v3 \
    -- uvx mcp-github-crunchtools

For the container version:

claude mcp add mcp-github-crunchtools \
    --env GITHUB_TOKEN=your_token_here \
    -- podman run -i --rm -e GITHUB_TOKEN quay.io/crunchtools/mcp-github

Usage Examples

List Issues

User: List open issues for crunchtools/mcp-github
Assistant: [calls list_issues_tool with owner="crunchtools", repo="mcp-github"]

Review a Pull Request

User: Show me the diff for PR #5 in crunchtools/mcp-github
Assistant: [calls get_pull_request_diff_tool with pull_number=5]

Check CI Status

User: Did the checks pass on pull request 5?
Assistant: [calls get_pull_request_checks_tool with pull_number=5]

Find Out Why CI Failed

User: Why did run 123456 fail?
Assistant: [calls get_failed_job_logs_tool with run_id=123456]

Answer a Review and Merge

User: Reply to the review findings on PR 5, then squash-merge it
Assistant: [calls list_pull_request_comments_tool with pull_number=5]
Assistant: [calls reply_to_review_comment_tool with comment_id=..., body="fixed in abc1234"]
Assistant: [calls get_pull_request_checks_tool with pull_number=5]
Assistant: [calls merge_pull_request_tool with merge_method="squash", sha=<head_sha from the checks>]
           (the tool checks the required checks again itself before merging)

Read a File

User: Show me src/server.py from crunchtools/mcp-github
Assistant: [calls get_file_content_tool with path="src/server.py"]

Search

User: Find code using FastMCP in crunchtools repos
Assistant: [calls search_code_tool with query="FastMCP org:crunchtools"]

Security

This server was designed with security as a primary concern. See SECURITY.md for details.

Key Security Features

1. Token Protection

   • Stored as SecretStr (never accidentally logged)

   • Environment variable only (never in files or args)

   • Optionally, a per-request token from the HTTP Authorization header, used for that request only and never stored on the shared client

   • Both sanitized from all error messages

2. Input Validation

   • Pydantic models for write inputs

   • Allowlist character validation for owner/repo names

   • Path traversal prevention for file reads

3. API Hardening

   • Bearer-token auth and pinned GitHub API version

   • HTTPS enforcement (except localhost)

   • TLS certificate validation

   • Request timeouts (30s)

   • Response size limits (10MB)

   • Job-log downloads follow GitHub's redirect without the token, over HTTPS only, and keep just the tail (20MB download limit)

   • Merges only when the required checks are green on the head commit, even for a token GitHub would let bypass them

4. Automated CVE Scanning

   • GitHub Actions scan dependencies

   • Container security scanning with Trivy

Development

Setup

git clone https://github.com/crunchtools/mcp-github.git
cd mcp-github
uv sync --all-extras

Run Tests

uv run pytest

Lint and Type Check

uv run ruff check src tests
uv run mypy src

Build Container

podman build -t mcp-github .

License

AGPL-3.0-or-later

Contributing

Contributions welcome! Please read SECURITY.md before submitting security-related changes.

Links

• GitHub REST API Documentation

• FastMCP Documentation

• MCP Specification

• crunchtools.com