Skip to main content
Glama

GitHub Flow MCP

Português (Brasil)

A policy-aware Model Context Protocol server for GitHub and GitHub Actions workflows. It is designed for AI-assisted infrastructure work where agents can inspect repositories and prepare changes, while remote mutations remain constrained by explicit preview-bound approval.

GitHub Flow MCP architecture

Why this exists

AI agents are useful at collecting context and preparing repetitive Git operations, but infrastructure workflows still need reviewability and guardrails. This MCP exposes a deliberately small GitHub surface:

  • repository, branch, pull request, review, and Actions inspection

  • local Git inspection without silent branch/commit/push/merge operations

  • branch and pull-request previews

  • short-lived, single-use confirmation tokens bound to the exact preview

  • optional Basecamp linkage

  • optional repository-specific label and reviewer policy

  • no merge tool, no branch deletion, no branch-protection changes, and no API-created commits

Related MCP server: github-mcp

Safety model

Remote write tools are not registered unless:

GITHUB_WRITE_ENABLED=true

When enabled, branch creation, pull-request creation, and PR comments still require a confirmation_id returned by their matching preview. The token is short-lived, single-use, and bound to the exact payload. If a branch source SHA, PR body, label set, reviewer set, or comment changes, a new preview is required.

NOTE

The MCP enforces preview-before-write and exact payload binding. The MCP host should only forward theconfirmation_id after actual human approval.

Installation

uv tool install git+https://github.com/thiagorchaves/github-flow-mcp.git

For development:

git clone https://github.com/thiagorchaves/github-flow-mcp.git
cd github-flow-mcp
uv sync --extra dev

Configuration

cp .env.example .env
chmod 600 .env

Use a fine-grained GitHub token with the minimum repositories and permissions needed. Typical permissions are Metadata read, Contents read/write for branch creation, Pull requests read/write, Issues read/write for labels/comments, Actions read, and Members read only when reviewer availability checks are required.

Organization-specific policy belongs in your local .env, not in the public repository. For example, you can require Basecamp links, configure a production branch marker, or require an AI-review label for selected repositories.

Kiro / MCP host example

{
  "mcpServers": {
    "github-flow": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/thiagorchaves/github-flow-mcp.git", "github-flow-mcp"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}",
        "GITHUB_DEFAULT_OWNER": "${GITHUB_DEFAULT_OWNER}",
        "GITHUB_INITIALS": "tc",
        "GITHUB_DEFAULT_BASE_BRANCH": "main",
        "GITHUB_LOCAL_REPOS_ROOT": "${HOME}/Projects",
        "GITHUB_WRITE_ENABLED": "false",
        "GITHUB_CONFIRMATION_TTL_SECONDS": "300"
      },
      "autoApprove": []
    }
  }
}

Tools

Read and diagnostics

  • healthcheck

  • get_authenticated_user

  • get_repository

  • list_branches

  • get_collaborator_permission

  • inspect_local_repository

  • list_pull_requests

  • get_pull_request

  • list_pull_request_files

  • list_pull_request_reviews

  • list_workflows

  • list_workflow_runs

Preview

  • preview_branch_name

  • preview_local_commit

  • preview_remote_branch

  • preview_pull_request

  • preview_pull_request_comment

Remote writes, registered only when enabled

  • create_remote_branch

  • create_pull_request

  • add_pull_request_comment

Basecamp handoff

  • build_basecamp_pr_update

This tool only generates Markdown. A Basecamp MCP can independently preview and publish that update.

  1. Retrieve the work-item context.

  2. Inspect the local repository without modifying it.

  3. Preview the branch and show it to the user.

  4. After approval, use the preview token to create the remote branch if needed.

  5. Edit and commit locally using your normal signed Git workflow.

  6. Push the branch.

  7. Preview the pull request.

  8. After approval, use its token to open the PR.

  9. Let humans review the PR and apply the infrastructure change through the normal delivery process.

Development

uv sync --extra dev
uv run ruff format --check .
uv run ruff check .
uv run mypy github_flow_mcp
uv run pytest

Security

Never commit .env, GitHub tokens, internal repository data, company-specific paths, or private work-item URLs. See SECURITY.md.

License

MIT. See LICENSE.

Available Tools

18 tools
build_basecamp_pr_updateC

Build Markdown for a separate Basecamp MCP without writing to Basecamp.

Inputs: repo (required), pull_number (required), owner, summary. Returns: object

get_authenticated_userD

Inputs: no named parameters. Returns: object

get_collaborator_permissionC

Checks whether a user/bot is a collaborator and returns repository permission.

Inputs: repo (required), username (required), owner. Returns: object

get_pull_requestC

Get a pull request by number.

Inputs: repo (required), pull_number (required), owner. Returns: object

get_repositoryB

Gets repository metadata and permissions.

Inputs: repo (required), owner. Returns: object

healthcheckD

Inputs: no named parameters. Returns: object

inspect_local_repositoryB

Inspects a local Git repository without changing files, branches, commits, or remotes.

Inputs: repo_path (required). Returns: object

list_branchesC

Lists repository branches.

Inputs: repo (required), owner, max_items. Returns: result

list_pull_request_filesC

List changed files in a pull request.

Inputs: repo (required), pull_number (required), owner, max_items. Returns: result

list_pull_request_reviewsC

List reviews for a pull request.

Inputs: repo (required), pull_number (required), owner. Returns: result

list_pull_requestsC

List pull requests ordered by most recently updated.

Inputs: repo (required), owner, state, max_items. Returns: result

list_workflow_runsC

Lists recent GitHub Actions workflow runs with optional filters.

Inputs: repo (required), event, owner, branch, +2 more. Returns: result

list_workflowsC

Lists GitHub Actions workflows in a repository.

Inputs: repo (required), owner. Returns: result

preview_branch_nameB

Builds and validates the branch name without creating the branch.

Inputs: description (required), environment, basecamp_url, source_branch. Returns: object

preview_local_commitB

Previews a local commit plan. This tool never creates commits.

Inputs: repo_path (required), basecamp_url (required), commit_message (required). Returns: object

preview_pull_requestB

Preview a pull request and issue a token bound to the exact final payload.

Inputs: body (required), head (required), repo (required), title (required), +6 more. Returns: object

preview_pull_request_commentC

Preview a PR timeline comment and issue a token for the exact body.

Inputs: body (required), repo (required), pull_number (required), owner. Returns: object

preview_remote_branchC

Preview a branch and issue a token bound to the exact source commit.

Inputs: repo (required), description (required), owner, environment, +2 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.2/5.0

    Scored across 18 tools

    Disambiguation2/5

    There is heavy overlap among the many 'preview_' tools: preview_branch_name, preview_local_commit, preview_remote_branch, preview_pull_request, and preview_pull_request_comment all follow a 'preview' pattern but differ in what they preview. More seriously, inspect_local_repository and preview_local_commit both involve inspecting local state, and several tools have empty descriptions (healthcheck, get_authenticated_user, get_repository, list_branches) that provide no cues for disambiguation, making misselection likely.

    Naming Consistency3/5

    Most tools follow a consistent verb_noun pattern (list_pull_requests, get_pull_request, list_branches, list_workflows). However, there is a notable deviation with build_basecamp_pr_update and healthcheck, and the 'preview_' family uses a verb style distinct from the rest of the set, creating a mixed but still readable convention.

    Tool Count4/5

    At 18 tools, the count is on the heavier side but reasonable for a GitHub workflow orchestration server that spans local inspection, PR operations, Basecamp integration, and CI workflows. Several tools feel edge-case specific (healthcheck, get_authenticated_user, list_collaborator_permission), but each has a defensible purpose.

    Completeness3/5

    The server covers core GitHub operations like listing/getting PRs, branches, workflows, and repository information. However, there are notable gaps: no create/update/merge pull request tools, no create/delete branch tools, and no workflow dispatch or run detail tools. The surface is read-inspection heavy but lacks the mutation actions expected of a 'workflow' server.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that enables AI assistants to interact with GitHub via a fine-grained personal access token — pushing commits, managing branches, opening and merging PRs, creating issues, and reading repositories. It runs locally with no telemetry and supports a read-only mode.
      15
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      A production-grade MCP server that provides LLMs with safe, structured, tool-based access to GitHub repositories, including issue management, semantic search, and guarded write operations.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      MCP server for auditable repository self-maintenance, turning GitHub issues and failed CI into independently verified pull requests with full audit trails, human approvals, and runbook archival.
      14
      344 npm
      3
      Apache 2.0