GitHub Master MCP

A local and remote MCP server that gives compatible AI clients tools to open, inspect, edit, test, commit, and manage GitHub repositories.

Two connection modes are available: local STDIO for desktop/local MCP clients, or remote Streamable HTTP at /mcp for clients that can connect to a remote MCP URL and send a Bearer token. Remote mode is protected by a separate high-entropy access token. The GitHub token stays on the server and is never sent to the AI client.

Important: publishing this repository on GitHub does not automatically make it appear in an AI app's plugin directory. The AI app must support remote MCP servers and the authentication method configured here. This version uses a static Bearer access token, not a GitHub OAuth sign-in flow or an app-directory listing.

What it can do

This release exposes the existing GitHub/project tools over either local STDIO or authenticated remote Streamable HTTP.

Project workflow

1. open_repository — paste a GitHub repository URL (or a /tree/branch URL); clone/fetch it locally and set it as the active project.

2. analyze_project — inspect project manifests, scripts, README, top-level files, and Git status.

3. list_project_files, read_project_file, search_project_code — explore the codebase.

4. write_project_file, delete_project_file — modify local project files.

5. git_status, git_diff — review changes.

6. run_project_script — run allow-listed project scripts when local command execution is enabled.

7. create_branch, commit_changes, push_branch, commit_and_push — prepare and send changes to GitHub with safeguards.

GitHub operations

• Verify the authenticated account (github_whoami).

• Create repositories for the authenticated user or an organization (create_repository).

• Create and list issues.

• Create and list pull requests; merge a pull request with confirmation.

• List GitHub Actions workflows and request a workflow run rerun with confirmation.

Repository discovery, details, branch/commit history, releases, workflow runs, and reruns are included. Repository forks are supported too. The available operations depend on the token's repository access and fine-grained permissions. This project intentionally does not expose repository deletion or arbitrary API passthrough tools.

Related MCP server: Git MCP Server

Requirements

• Node.js 20.6 or newer (Node 22 LTS or newer recommended).

• Git installed and available on PATH.

• A GitHub fine-grained Personal Access Token for private repositories and write operations.

• An MCP-compatible AI application that supports local STDIO or remote Streamable HTTP with Bearer-token headers.

Install

git clone https://github.com/YOUR_USERNAME/github-master-mcp.git
cd github-master-mcp
npm install
cp .env.example .env

Edit .env and set at least:

GITHUB_TOKEN=github_pat_your_token_here
GITHUB_MCP_WORKSPACE=./workspaces
GITHUB_MCP_MODE=edit
GITHUB_MCP_ALLOW_PUSH=false
GITHUB_MCP_CONFIRMATION_PHRASE=use-a-long-private-phrase-here
GITHUB_MCP_ALLOW_COMMANDS=false
GITHUB_MCP_ALLOWED_SCRIPTS=test,build,lint,typecheck,check

Never commit .env, paste your token into an AI chat, or share the confirmation phrase. .env is ignored by Git.

Remote MCP deployment (Render)

Remote mode makes the MCP endpoint reachable over HTTPS so a compatible AI client can connect by URL. The endpoint is /mcp; /healthz is a public health check. Remote mode is single-owner: every authenticated connection uses the GitHub token configured on this server. Do not share the endpoint and access token with other people.

1. Prepare secrets

Install dependencies locally, then generate a separate remote access token:

npm install
npm run generate:token

Copy the generated value somewhere private. It is the MCP connection password; it is not your GitHub token. Also prepare a GitHub fine-grained PAT with access only to the repositories you intend the server to manage.

2. Deploy the repository

Push this project to your GitHub repository, then create a Render Web Service from that repository. Render can read the included render.yaml. In the service Environment settings, add these secrets:

• GITHUB_TOKEN — your GitHub fine-grained PAT.

• GITHUB_MCP_ACCESS_TOKEN — the generated random bearer token.

• GITHUB_MCP_CONFIRMATION_PHRASE — a separate private phrase used to approve destructive actions.

The blueprint sets remote HTTP mode, editing enabled, and push/command execution disabled by default. Keep those safe defaults initially. Render supplies PORT; the service binds to 0.0.0.0.

When the deploy is live, your MCP URL is:

https://YOUR-SERVICE.onrender.com/mcp

Health check:

https://YOUR-SERVICE.onrender.com/healthz

3. Connect an MCP client

In an MCP client that supports remote Streamable HTTP and custom Bearer headers, connect to the /mcp URL and set this header:

Authorization: Bearer YOUR_GITHUB_MCP_ACCESS_TOKEN

Some clients expose this as an Authentication/API key field instead of a custom header. Their setup screens differ; use the exact option for that client. examples/remote-mcp.json is only a generic configuration example, not a universal config format.

4. Start working

Once connected, ask the AI to open a repository URL, analyze it, and make changes. Example:

Open https://github.com/OWNER/REPO. Analyze the project structure and important files.
Make the requested changes, preserve the current stack and existing behavior,
run the available checks, and show me the final diff. Do not commit or push until
I explicitly approve.

Remote-mode limitations

• This is a private, single-owner remote MCP server using one GitHub PAT. It is not yet multi-user GitHub OAuth, and this code does not publish an app to any AI app directory.

• A client must support remote MCP plus the configured Bearer authentication. A URL alone does not grant access.

• Keep GITHUB_MCP_ALLOW_PUSH=false until you are ready. To enable pushing, set it to true in the host environment and redeploy; commit/push tools still require the confirmation phrase.

• Keep GITHUB_MCP_ALLOW_COMMANDS=false. Repository scripts can execute arbitrary code and are disabled by default.

• Render free services may sleep or restart. The working clone is not guaranteed to survive a restart; call open_repository again after reconnecting.

• Never place GitHub PATs, bearer tokens, or confirmation phrases in source files, commit history, or public chat.

GitHub token permissions

Create a fine-grained token and limit it to only the repositories you need. For normal project editing and pushing, grant repository Contents: Read and write. Add only what you need for the optional tools:

• Repository creation: Repository creation: Write or Administration: Write, depending on the endpoint/account type; organization creation may require additional organization-level rights.

• Issues: Issues: Read and write.

• Pull requests: Pull requests: Read and write; merge operations also require contents write access.

• GitHub Actions list/rerun: Actions: Read for listing and Actions: Write for rerunning.

• Private repository checkout: token must include the selected repository and Contents read access.

GitHub changes its fine-grained permission requirements by endpoint. Check the live GitHub permissions reference if an endpoint returns 403/404. A token cannot grant access beyond the account's own repository/org rights.

Connect to an AI client

The examples in examples/ show common STDIO configuration shapes. Replace /ABSOLUTE/PATH with the actual absolute path to this project. The command passes the .env file explicitly using Node's --env-file option so it does not matter which directory the AI client starts in.

Claude Desktop

Copy the contents of examples/claude-desktop.config.json into your Claude Desktop MCP configuration and replace the paths. Restart Claude Desktop.

Cursor

Use the configuration in examples/cursor.mcp.json in your MCP configuration (commonly .cursor/mcp.json in a project, or the global MCP configuration UI). Replace the paths and reload MCP servers.

OpenCode

Merge examples/opencode.json into your OpenCode config and replace the paths. Do not overwrite other existing config entries; merge the mcp.github-master object.

Other MCP-compatible hosts use the same STDIO launch command:

node --env-file=/absolute/path/github-master-mcp/.env /absolute/path/github-master-mcp/src/index.js

If your client supports environment variables directly, you can pass the .env values in its MCP server environment instead of using --env-file.

How to use it in chat

After the MCP server shows as connected, paste a repository URL and ask the AI to work on it. Example:

Open https://github.com/owner/repository, analyze the whole project, then redesign the settings page. Preserve the existing stack and behavior. Inspect the relevant files first, make the smallest safe changes, and show me the Git diff. Do not commit or push yet.

Then review the AI's changes using git_status and git_diff. If satisfied, explicitly ask it to commit. The tool requires your private phrase. To push, GITHUB_MCP_ALLOW_PUSH=true must also be enabled in your local .env, and the owner must provide the phrase in the conversation when approving that push.

Useful prompt

Use GitHub Master MCP. Open this repository: <PASTE_REPOSITORY_URL>
First analyze the project structure, framework, dependencies, and important flows.
Before editing, inspect the relevant files and explain the implementation plan.
Make the requested changes in the local checkout. Preserve existing UI, routes,
APIs, and features unless I specifically ask to change them. Do not fabricate
files or claim tests passed unless you ran them. Run only the available safe
checks, inspect the final diff, and do not commit or push until I explicitly approve.

Security model and defaults

• Authentication: remote /mcp calls require a high-entropy Bearer token checked before MCP requests reach the tools.

• Local checkout: code edits are made in the selected local workspace; opening a repo does not push anything.

• Push disabled by default: set GITHUB_MCP_ALLOW_PUSH=true only when you are ready to permit remote pushes.

• Confirmation phrase: commit, push, PR merge, workflow rerun, and file deletion require the local phrase configured in .env. The owner should only disclose it in chat when approving that exact action.

• Command execution disabled by default: project scripts can execute repository-controlled code. Enable GITHUB_MCP_ALLOW_COMMANDS=true only for repositories you trust. Only script names in GITHUB_MCP_ALLOWED_SCRIPTS are accepted, each run has a timeout, and the GitHub token/approval phrase are stripped from the script environment. Git hooks are disabled for MCP-managed Git commands.

• Secret-file guard: .env files, private keys, certificate bundles, common credential files, .git, and node_modules are blocked from file tools; secret-like paths are also excluded from automatic commit staging.

• Path guard: absolute paths, parent traversal, and protected internal directories are blocked.

• Least privilege: use a fine-grained token restricted to selected repositories and minimum permissions.

The confirmation phrase is an additional guard, not a replacement for the AI client's own tool-approval UI or a trusted local machine. Do not enable write/push permissions for an AI client you do not trust.

Configuration reference

Troubleshooting

• MCP server not starting: confirm Node 20+, run npm install, then run npm run check. Check the MCP client logs. In STDIO mode, stdout is reserved for MCP protocol messages.

• git not found: install Git and make sure git --version works in the same environment used by your AI client.

• 401/403/404 from GitHub: check that the token is valid, has access to that repository, and has the endpoint-specific fine-grained permissions. GitHub may return 404 for private repositories the token cannot access.

• Remote endpoint returns 401: confirm the client sends Authorization: Bearer ... and that it exactly matches GITHUB_MCP_ACCESS_TOKEN on the host.

• HTTP mode does not start: confirm GITHUB_MCP_TRANSPORT=http, GITHUB_TOKEN, and a 32+ character GITHUB_MCP_ACCESS_TOKEN are set.

• Private clone fails: confirm GITHUB_TOKEN is set on the server, has Contents read access, and includes that repository.

• Push blocked: confirm local changes are committed, GITHUB_MCP_ALLOW_PUSH=true, the configured phrase is set, and the token has Contents write access.

• Command execution blocked: by design. Set GITHUB_MCP_ALLOW_COMMANDS=true only for a trusted repo and allow the needed script name.

Git author setup

Before creating commits, configure your Git author once on the machine if it is not already set:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

Development

npm run check
npm test

License

MIT. See LICENSE.