GitHub Flow MCP
Generates Markdown updates for Basecamp that can be independently previewed and published via a Basecamp MCP.
Provides tools for inspecting GitHub repositories, branches, pull requests, reviews, and authenticated user information, as well as preview-bound mutations for creating remote branches and pull requests.
Provides tools for listing and inspecting GitHub Actions workflows and workflow runs.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@GitHub Flow MCP preview a pull request for my latest local commit on main"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
GitHub Flow MCP
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.
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=trueWhen 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.
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.gitFor development:
git clone https://github.com/thiagorchaves/github-flow-mcp.git
cd github-flow-mcp
uv sync --extra devConfiguration
cp .env.example .env
chmod 600 .envUse 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
healthcheckget_authenticated_userget_repositorylist_branchesget_collaborator_permissioninspect_local_repositorylist_pull_requestsget_pull_requestlist_pull_request_fileslist_pull_request_reviewslist_workflowslist_workflow_runs
Preview
preview_branch_namepreview_local_commitpreview_remote_branchpreview_pull_requestpreview_pull_request_comment
Remote writes, registered only when enabled
create_remote_branchcreate_pull_requestadd_pull_request_comment
Basecamp handoff
build_basecamp_pr_update
This tool only generates Markdown. A Basecamp MCP can independently preview and publish that update.
Recommended workflow
Retrieve the work-item context.
Inspect the local repository without modifying it.
Preview the branch and show it to the user.
After approval, use the preview token to create the remote branch if needed.
Edit and commit locally using your normal signed Git workflow.
Push the branch.
Preview the pull request.
After approval, use its token to open the PR.
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 pytestSecurity
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 toolsbuild_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
Scored across 18 tools
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.
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.
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.
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
Zero-log MCP server with 49 tools for AI guardrails, secret scanning, MCP linting & EU compliance.
AI-native git hosting — repos, PRs, issues, CI gates, and AI code review over MCP (60 tools).
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA self-hosted GitHub MCP server with per-repository guardrails for AI agents, enabling fine-grained access control and audit trails.-
- AlicenseAqualityDmaintenanceAn 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.151MIT
- AlicenseNot gradedqualityBmaintenanceA 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
- AlicenseAqualityBmaintenanceMCP 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.14344 npm3Apache 2.0