From ed6c6711135fc38256b753bf5b7273bb2575308c Mon Sep 17 00:00:00 2001 From: Sam Morrow Date: Fri, 26 Jun 2026 12:28:51 +0200 Subject: [PATCH 1/3] docs: lead local/stdio install with OAuth login Surface OAuth 2.1 login as a first-class option above the Personal Access Token in the README install section and in every local-capable installation guide, each in that client's own config syntax, linking to the dedicated docs/oauth-login.md guide. The github.com OAuth example needs no token; in Docker it publishes a fixed callback port to loopback (-p 127.0.0.1:8085:8085). The PAT block is retained below it and noted as taking precedence over OAuth. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 33 ++++++- .../install-antigravity.md | 29 ++++++ docs/installation-guides/install-claude.md | 68 ++++++++++++++ docs/installation-guides/install-cline.md | 27 +++++- docs/installation-guides/install-codex.md | 22 ++++- .../install-copilot-cli.md | 29 ++++++ docs/installation-guides/install-cursor.md | 29 ++++++ .../installation-guides/install-gemini-cli.md | 34 ++++++- docs/installation-guides/install-opencode.md | 27 ++++++ .../install-other-copilot-ides.md | 91 ++++++++++++++++++- docs/installation-guides/install-roo-code.md | 25 +++++ docs/installation-guides/install-windsurf.md | 29 ++++++ docs/installation-guides/install-xcode.md | 2 + docs/installation-guides/install-zed.md | 25 +++++ 14 files changed, 464 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 9be25a4e0..bb1791ea4 100644 --- a/README.md +++ b/README.md @@ -280,9 +280,38 @@ More about using MCP server tools in VS Code's [agent mode documentation](https: Install in GitHub Copilot on other IDEs (JetBrains, Visual Studio, Eclipse, etc.) -Add the following JSON block to your IDE's MCP settings. +Add one of the following JSON blocks to your IDE's MCP settings. -> The examples below authenticate with a Personal Access Token. To log in with OAuth instead (no token to create or store), see **[Local Server OAuth Login](docs/oauth-login.md)** — in Docker it needs a fixed callback port, as the one-click buttons above show. +**Log in with OAuth (no token to create or store).** On github.com you can start the server with no token at all: it runs a browser-based login on first use and keeps the resulting token **in memory only**. In Docker this needs a fixed callback port published to loopback so the container's login callback is reachable: + +```json +{ + "mcp": { + "servers": { + "github": { + "command": "docker", + "args": [ + "run", + "-i", + "--rm", + "-p", + "127.0.0.1:8085:8085", + "-e", + "GITHUB_OAUTH_CALLBACK_PORT", + "ghcr.io/github/github-mcp-server" + ], + "env": { + "GITHUB_OAUTH_CALLBACK_PORT": "8085" + } + } + } + } +} +``` + +See **[Local Server OAuth Login](docs/oauth-login.md)** for the native-binary flow (no fixed port needed), the headless/device-code fallback, GitHub Enterprise Server / `ghe.com`, and bringing your own OAuth or GitHub App. + +**Or authenticate with a Personal Access Token.** Set `GITHUB_PERSONAL_ACCESS_TOKEN` instead (it takes precedence over OAuth): ```json { diff --git a/docs/installation-guides/install-antigravity.md b/docs/installation-guides/install-antigravity.md index c24d8e01d..eced26a82 100644 --- a/docs/installation-guides/install-antigravity.md +++ b/docs/installation-guides/install-antigravity.md @@ -75,6 +75,35 @@ Close and reopen Antigravity for the changes to take effect. If you prefer running the server locally with Docker: +On github.com you can skip the token entirely: the server opens a browser login on first use and keeps the credential in memory only. In Docker, publish a fixed callback port to loopback: + +```json +{ + "mcpServers": { + "github": { + "command": "docker", + "args": [ + "run", + "-i", + "--rm", + "-p", + "127.0.0.1:8085:8085", + "-e", + "GITHUB_OAUTH_CALLBACK_PORT", + "ghcr.io/github/github-mcp-server" + ], + "env": { + "GITHUB_OAUTH_CALLBACK_PORT": "8085" + } + } + } +} +``` + +See **[Local Server OAuth Login](../oauth-login.md)** for the native-binary flow (no fixed port), headless/device-code fallback, GitHub Enterprise, and bringing your own OAuth or GitHub App. + +To authenticate with a Personal Access Token instead (it takes precedence over OAuth): + ```json { "mcpServers": { diff --git a/docs/installation-guides/install-claude.md b/docs/installation-guides/install-claude.md index d66b34776..4374472c0 100644 --- a/docs/installation-guides/install-claude.md +++ b/docs/installation-guides/install-claude.md @@ -63,6 +63,16 @@ claude mcp add-json github "{`"type`":`"http`",`"url`":`"https://api.githubcopil ### Local Server Setup (Docker required) ### With Docker + +On github.com you can skip the token entirely: the server opens a browser login on first use and keeps the credential in memory only. In Docker, publish a fixed callback port to loopback. Run the following command in the terminal (not in Claude Code CLI): + +```bash +claude mcp add github -e GITHUB_OAUTH_CALLBACK_PORT=8085 -- docker run -i --rm -p 127.0.0.1:8085:8085 -e GITHUB_OAUTH_CALLBACK_PORT ghcr.io/github/github-mcp-server +``` + +See **[Local Server OAuth Login](../oauth-login.md)** for the native-binary flow (no fixed port), headless/device-code fallback, GitHub Enterprise, and bringing your own OAuth or GitHub App. + +To authenticate with a Personal Access Token instead (it takes precedence over OAuth): 1. Run the following command in the terminal (not in Claude Code CLI): ```bash claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=YOUR_GITHUB_PAT -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server @@ -136,6 +146,35 @@ claude mcp add github --transport http https://api.githubcopilot.com/mcp/ -H "Au Add this codeblock to your `claude_desktop_config.json`: +On github.com you can skip the token entirely: the server opens a browser login on first use and keeps the credential in memory only. In Docker, publish a fixed callback port to loopback: + +```json +{ + "mcpServers": { + "github": { + "command": "docker", + "args": [ + "run", + "-i", + "--rm", + "-p", + "127.0.0.1:8085:8085", + "-e", + "GITHUB_OAUTH_CALLBACK_PORT", + "ghcr.io/github/github-mcp-server" + ], + "env": { + "GITHUB_OAUTH_CALLBACK_PORT": "8085" + } + } + } +} +``` + +See **[Local Server OAuth Login](../oauth-login.md)** for the native-binary flow (no fixed port), headless/device-code fallback, GitHub Enterprise, and bringing your own OAuth or GitHub App. + +To authenticate with a Personal Access Token instead (it takes precedence over OAuth): + ```json { "mcpServers": { @@ -212,6 +251,35 @@ Or open the file in a text editor and add the `mcpServers` block manually: > **macOS note**: Xcode runs with a minimal `PATH` that typically excludes `/usr/local/bin` (Intel) and `/opt/homebrew/bin` (Apple Silicon). Use the full path to `docker` to ensure it can be found. Run `which docker` in Terminal to find the correct path on your system. +On github.com you can skip the token entirely: the server opens a browser login on first use and keeps the credential in memory only. In Docker, publish a fixed callback port to loopback: + +```json +{ + "mcpServers": { + "github": { + "command": "/usr/local/bin/docker", + "args": [ + "run", + "-i", + "--rm", + "-p", + "127.0.0.1:8085:8085", + "-e", + "GITHUB_OAUTH_CALLBACK_PORT", + "ghcr.io/github/github-mcp-server" + ], + "env": { + "GITHUB_OAUTH_CALLBACK_PORT": "8085" + } + } + } +} +``` + +See **[Local Server OAuth Login](../oauth-login.md)** for the native-binary flow (no fixed port), headless/device-code fallback, GitHub Enterprise, and bringing your own OAuth or GitHub App. + +To authenticate with a Personal Access Token instead (it takes precedence over OAuth): + ```json { "mcpServers": { diff --git a/docs/installation-guides/install-cline.md b/docs/installation-guides/install-cline.md index 6bc643cb6..fd11d51e6 100644 --- a/docs/installation-guides/install-cline.md +++ b/docs/installation-guides/install-cline.md @@ -29,7 +29,32 @@ Replace `YOUR_GITHUB_PAT` with your [GitHub Personal Access Token](https://githu ## Local Server (Docker) 1. Click the Cline icon in your editor's sidebar (or open the command palette and search for "Cline"), then click the **MCP Servers** icon (server stack icon at the top of the Cline panel), and click **"Configure MCP Servers"** to open `cline_mcp_settings.json`. -2. Add the configuration below, replacing `YOUR_GITHUB_PAT` with your [GitHub Personal Access Token](https://github.com/settings/tokens). +2. Add one of the configurations below. The OAuth option needs no token; for the PAT option, replace `YOUR_GITHUB_PAT` with your [GitHub Personal Access Token](https://github.com/settings/tokens). + +On github.com you can skip the token entirely: the server opens a browser login on first use and keeps the credential in memory only. In Docker, publish a fixed callback port to loopback: + +```json +{ + "mcpServers": { + "github": { + "command": "docker", + "args": [ + "run", "-i", "--rm", + "-p", "127.0.0.1:8085:8085", + "-e", "GITHUB_OAUTH_CALLBACK_PORT", + "ghcr.io/github/github-mcp-server" + ], + "env": { + "GITHUB_OAUTH_CALLBACK_PORT": "8085" + } + } + } +} +``` + +See **[Local Server OAuth Login](../oauth-login.md)** for the native-binary flow (no fixed port), headless/device-code fallback, GitHub Enterprise, and bringing your own OAuth or GitHub App. + +To authenticate with a Personal Access Token instead (it takes precedence over OAuth): ```json { diff --git a/docs/installation-guides/install-codex.md b/docs/installation-guides/install-codex.md index af2444588..e06737c93 100644 --- a/docs/installation-guides/install-codex.md +++ b/docs/installation-guides/install-codex.md @@ -45,7 +45,27 @@ echo -e ".env" >> .gitignore ## Local Docker Configuration -Use this if you prefer a local, self-hosted instance instead of the remote HTTP server, please refer to the [OpenAI documentation for configuration](https://developers.openai.com/codex/mcp). +Use this if you prefer a local, self-hosted instance instead of the remote HTTP server. See the [OpenAI documentation for configuration](https://developers.openai.com/codex/mcp) for the authoritative schema. + +On github.com you can skip the token entirely: the server opens a browser login on first use and keeps the credential in memory only. In Docker, publish a fixed callback port to loopback: + +```toml +[mcp_servers.github] +command = "docker" +args = ["run", "-i", "--rm", "-p", "127.0.0.1:8085:8085", "-e", "GITHUB_OAUTH_CALLBACK_PORT", "ghcr.io/github/github-mcp-server"] +env = { GITHUB_OAUTH_CALLBACK_PORT = "8085" } +``` + +See **[Local Server OAuth Login](../oauth-login.md)** for the native-binary flow (no fixed port), headless/device-code fallback, GitHub Enterprise, and bringing your own OAuth or GitHub App. + +To authenticate with a Personal Access Token instead (it takes precedence over OAuth): + +```toml +[mcp_servers.github] +command = "docker" +args = ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"] +env = { GITHUB_PERSONAL_ACCESS_TOKEN = "ghp_your_token_here" } +``` ## Verification diff --git a/docs/installation-guides/install-copilot-cli.md b/docs/installation-guides/install-copilot-cli.md index 4ac5b3712..7249e0331 100644 --- a/docs/installation-guides/install-copilot-cli.md +++ b/docs/installation-guides/install-copilot-cli.md @@ -95,6 +95,35 @@ For additional options like toolsets and read-only mode, see the [remote server With Docker running, you can run the GitHub MCP server in a container: +On github.com you can skip the token entirely: the server opens a browser login on first use and keeps the credential in memory only. In Docker, publish a fixed callback port to loopback: + +```json +{ + "mcpServers": { + "github": { + "command": "docker", + "args": [ + "run", + "-i", + "--rm", + "-p", + "127.0.0.1:8085:8085", + "-e", + "GITHUB_OAUTH_CALLBACK_PORT", + "ghcr.io/github/github-mcp-server" + ], + "env": { + "GITHUB_OAUTH_CALLBACK_PORT": "8085" + } + } + } +} +``` + +See **[Local Server OAuth Login](../oauth-login.md)** for the native-binary flow (no fixed port), headless/device-code fallback, GitHub Enterprise, and bringing your own OAuth or GitHub App. + +To authenticate with a Personal Access Token instead (it takes precedence over OAuth): + ```json { "mcpServers": { diff --git a/docs/installation-guides/install-cursor.md b/docs/installation-guides/install-cursor.md index 654f0a788..305f95bc7 100644 --- a/docs/installation-guides/install-cursor.md +++ b/docs/installation-guides/install-cursor.md @@ -51,6 +51,35 @@ The local GitHub MCP server runs via Docker and requires Docker Desktop to be in ### Docker Configuration +On github.com you can skip the token entirely: the server opens a browser login on first use and keeps the credential in memory only. In Docker, publish a fixed callback port to loopback: + +```json +{ + "mcpServers": { + "github": { + "command": "docker", + "args": [ + "run", + "-i", + "--rm", + "-p", + "127.0.0.1:8085:8085", + "-e", + "GITHUB_OAUTH_CALLBACK_PORT", + "ghcr.io/github/github-mcp-server" + ], + "env": { + "GITHUB_OAUTH_CALLBACK_PORT": "8085" + } + } + } +} +``` + +See **[Local Server OAuth Login](../oauth-login.md)** for the native-binary flow (no fixed port), headless/device-code fallback, GitHub Enterprise, and bringing your own OAuth or GitHub App. + +To authenticate with a Personal Access Token instead (it takes precedence over OAuth): + ```json { "mcpServers": { diff --git a/docs/installation-guides/install-gemini-cli.md b/docs/installation-guides/install-gemini-cli.md index 20764384c..7c5d82927 100644 --- a/docs/installation-guides/install-gemini-cli.md +++ b/docs/installation-guides/install-gemini-cli.md @@ -59,7 +59,37 @@ You can also connect to the hosted MCP server directly. After securely storing y ### Method 3: Local Docker -With docker running, you can run the GitHub MCP server in a container: +With docker running, you can run the GitHub MCP server in a container. + +On github.com you can skip the token entirely: the server opens a browser login on first use and keeps the credential in memory only. In Docker, publish a fixed callback port to loopback: + +```json +// ~/.gemini/settings.json +{ + "mcpServers": { + "github": { + "command": "docker", + "args": [ + "run", + "-i", + "--rm", + "-p", + "127.0.0.1:8085:8085", + "-e", + "GITHUB_OAUTH_CALLBACK_PORT", + "ghcr.io/github/github-mcp-server" + ], + "env": { + "GITHUB_OAUTH_CALLBACK_PORT": "8085" + } + } + } +} +``` + +See **[Local Server OAuth Login](../oauth-login.md)** for the native-binary flow (no fixed port), headless/device-code fallback, GitHub Enterprise, and bringing your own OAuth or GitHub App. + +To authenticate with a Personal Access Token instead (it takes precedence over OAuth): ```json // ~/.gemini/settings.json @@ -104,6 +134,8 @@ Then, replacing `/path/to/binary` with the actual path to your binary, configure } ``` +To log in with OAuth instead of a PAT (no token to create or store), omit `GITHUB_PERSONAL_ACCESS_TOKEN` — the native binary uses a random loopback callback port, so no extra configuration is needed. See **[Local Server OAuth Login](../oauth-login.md)**. + ## Verification To verify that the GitHub MCP server has been configured, start Gemini CLI in your terminal with `gemini`, then: diff --git a/docs/installation-guides/install-opencode.md b/docs/installation-guides/install-opencode.md index 10e0e2db2..c572f3f8c 100644 --- a/docs/installation-guides/install-opencode.md +++ b/docs/installation-guides/install-opencode.md @@ -61,6 +61,33 @@ Set `GITHUB_PERSONAL_ACCESS_TOKEN` in your shell environment before starting Ope The local GitHub MCP server runs via Docker and requires Docker Desktop (or another Docker runtime) to be installed and running. +On github.com you can skip the token entirely: the server opens a browser login on first use and keeps the credential in memory only. In Docker, publish a fixed callback port to loopback: + +```json +{ + "$schema": "https://opencode.ai/config.json", + "mcp": { + "github": { + "type": "local", + "command": [ + "docker", "run", "-i", "--rm", + "-p", "127.0.0.1:8085:8085", + "-e", "GITHUB_OAUTH_CALLBACK_PORT", + "ghcr.io/github/github-mcp-server" + ], + "enabled": true, + "environment": { + "GITHUB_OAUTH_CALLBACK_PORT": "8085" + } + } + } +} +``` + +See **[Local Server OAuth Login](../oauth-login.md)** for the native-binary flow (no fixed port), headless/device-code fallback, GitHub Enterprise, and bringing your own OAuth or GitHub App. + +To authenticate with a Personal Access Token instead (it takes precedence over OAuth): + ```json { "$schema": "https://opencode.ai/config.json", diff --git a/docs/installation-guides/install-other-copilot-ides.md b/docs/installation-guides/install-other-copilot-ides.md index a3200179c..9ae9572cb 100644 --- a/docs/installation-guides/install-other-copilot-ides.md +++ b/docs/installation-guides/install-other-copilot-ides.md @@ -40,7 +40,27 @@ For users who prefer to run the GitHub MCP server locally. Requires Docker insta #### Configuration 1. Create an `.mcp.json` file in your solution or %USERPROFILE% directory. -2. Add this configuration: +2. Add this configuration. On github.com you can skip the token entirely: the server opens a browser login on first use and keeps the credential in memory only. In Docker, publish a fixed callback port to loopback: +```json +{ + "servers": { + "github": { + "type": "stdio", + "command": "docker", + "args": [ + "run", "-i", "--rm", "-p", "127.0.0.1:8085:8085", "-e", "GITHUB_OAUTH_CALLBACK_PORT", + "ghcr.io/github/github-mcp-server" + ], + "env": { + "GITHUB_OAUTH_CALLBACK_PORT": "8085" + } + } + } +} +``` +See **[Local Server OAuth Login](../oauth-login.md)** for the native-binary flow (no fixed port), headless/device-code fallback, GitHub Enterprise, and bringing your own OAuth or GitHub App. + +To authenticate with a Personal Access Token instead (it takes precedence over OAuth): ```json { "inputs": [ @@ -109,6 +129,29 @@ The remote GitHub MCP server is hosted by GitHub and provides automatic updates For users who prefer to run the GitHub MCP server locally. Requires Docker installed and running. #### Configuration + +On github.com you can skip the token entirely: the server opens a browser login on first use and keeps the credential in memory only. In Docker, publish a fixed callback port to loopback: +```json +{ + "servers": { + "github": { + "command": "docker", + "args": [ + "run", "-i", "--rm", + "-p", "127.0.0.1:8085:8085", + "-e", "GITHUB_OAUTH_CALLBACK_PORT", + "ghcr.io/github/github-mcp-server" + ], + "env": { + "GITHUB_OAUTH_CALLBACK_PORT": "8085" + } + } + } +} +``` +See **[Local Server OAuth Login](../oauth-login.md)** for the native-binary flow (no fixed port), headless/device-code fallback, GitHub Enterprise, and bringing your own OAuth or GitHub App. + +To authenticate with a Personal Access Token instead (it takes precedence over OAuth): ```json { "servers": { @@ -165,6 +208,29 @@ The remote GitHub MCP server is hosted by GitHub and provides automatic updates For users who prefer to run the GitHub MCP server locally. Requires Docker installed and running. #### Configuration + +On github.com you can skip the token entirely: the server opens a browser login on first use and keeps the credential in memory only. In Docker, publish a fixed callback port to loopback: +```json +{ + "servers": { + "github": { + "command": "docker", + "args": [ + "run", "-i", "--rm", + "-p", "127.0.0.1:8085:8085", + "-e", "GITHUB_OAUTH_CALLBACK_PORT", + "ghcr.io/github/github-mcp-server" + ], + "env": { + "GITHUB_OAUTH_CALLBACK_PORT": "8085" + } + } + } +} +``` +See **[Local Server OAuth Login](../oauth-login.md)** for the native-binary flow (no fixed port), headless/device-code fallback, GitHub Enterprise, and bringing your own OAuth or GitHub App. + +To authenticate with a Personal Access Token instead (it takes precedence over OAuth): ```json { "servers": { @@ -222,6 +288,29 @@ The remote GitHub MCP server is hosted by GitHub and provides automatic updates For users who prefer to run the GitHub MCP server locally. Requires Docker installed and running. #### Configuration + +On github.com you can skip the token entirely: the server opens a browser login on first use and keeps the credential in memory only. In Docker, publish a fixed callback port to loopback: +```json +{ + "servers": { + "github": { + "command": "docker", + "args": [ + "run", "-i", "--rm", + "-p", "127.0.0.1:8085:8085", + "-e", "GITHUB_OAUTH_CALLBACK_PORT", + "ghcr.io/github/github-mcp-server" + ], + "env": { + "GITHUB_OAUTH_CALLBACK_PORT": "8085" + } + } + } +} +``` +See **[Local Server OAuth Login](../oauth-login.md)** for the native-binary flow (no fixed port), headless/device-code fallback, GitHub Enterprise, and bringing your own OAuth or GitHub App. + +To authenticate with a Personal Access Token instead (it takes precedence over OAuth): ```json { "servers": { diff --git a/docs/installation-guides/install-roo-code.md b/docs/installation-guides/install-roo-code.md index 77513fb55..c3ab25222 100644 --- a/docs/installation-guides/install-roo-code.md +++ b/docs/installation-guides/install-roo-code.md @@ -33,6 +33,31 @@ To customize toolsets, add server-side headers like `X-MCP-Toolsets` or `X-MCP-R ## Local Server (Docker) +On github.com you can skip the token entirely: the server opens a browser login on first use and keeps the credential in memory only. In Docker, publish a fixed callback port to loopback: + +```json +{ + "mcpServers": { + "github": { + "command": "docker", + "args": [ + "run", "-i", "--rm", + "-p", "127.0.0.1:8085:8085", + "-e", "GITHUB_OAUTH_CALLBACK_PORT", + "ghcr.io/github/github-mcp-server" + ], + "env": { + "GITHUB_OAUTH_CALLBACK_PORT": "8085" + } + } + } +} +``` + +See **[Local Server OAuth Login](../oauth-login.md)** for the native-binary flow (no fixed port), headless/device-code fallback, GitHub Enterprise, and bringing your own OAuth or GitHub App. + +To authenticate with a Personal Access Token instead (replace `YOUR_GITHUB_PAT`; it takes precedence over OAuth): + ```json { "mcpServers": { diff --git a/docs/installation-guides/install-windsurf.md b/docs/installation-guides/install-windsurf.md index 8793e2edb..c19e7b7c2 100644 --- a/docs/installation-guides/install-windsurf.md +++ b/docs/installation-guides/install-windsurf.md @@ -30,6 +30,35 @@ Windsurf supports Streamable HTTP servers with a `serverUrl` field: ### Docker Installation (Required) **Important**: The npm package `@modelcontextprotocol/server-github` is no longer supported as of April 2025. Use the official Docker image `ghcr.io/github/github-mcp-server` instead. +On github.com you can skip the token entirely: the server opens a browser login on first use and keeps the credential in memory only. In Docker, publish a fixed callback port to loopback: + +```json +{ + "mcpServers": { + "github": { + "command": "docker", + "args": [ + "run", + "-i", + "--rm", + "-p", + "127.0.0.1:8085:8085", + "-e", + "GITHUB_OAUTH_CALLBACK_PORT", + "ghcr.io/github/github-mcp-server" + ], + "env": { + "GITHUB_OAUTH_CALLBACK_PORT": "8085" + } + } + } +} +``` + +See **[Local Server OAuth Login](../oauth-login.md)** for the native-binary flow (no fixed port), headless/device-code fallback, GitHub Enterprise, and bringing your own OAuth or GitHub App. + +To authenticate with a Personal Access Token instead (it takes precedence over OAuth): + ```json { "mcpServers": { diff --git a/docs/installation-guides/install-xcode.md b/docs/installation-guides/install-xcode.md index 15bcfde34..f1c38bad1 100644 --- a/docs/installation-guides/install-xcode.md +++ b/docs/installation-guides/install-xcode.md @@ -29,6 +29,8 @@ Xcode runs with a minimal `PATH` that typically excludes common binary locations | Homebrew (Intel Mac) | `/usr/local/bin/` | | Homebrew (Apple Silicon) | `/opt/homebrew/bin/` | +> **Logging in with OAuth?** You can run the local server with no PAT — it opens a browser login on first use and keeps the token in memory only. With Docker this needs a fixed callback port published to loopback (`-p 127.0.0.1:8085:8085 -e GITHUB_OAUTH_CALLBACK_PORT` with `GITHUB_OAUTH_CALLBACK_PORT=8085`); a native binary uses a random loopback port and needs no extra configuration. See **[Local Server OAuth Login](../oauth-login.md)**. + ## Troubleshooting | Issue | Possible Cause | Fix | diff --git a/docs/installation-guides/install-zed.md b/docs/installation-guides/install-zed.md index d0e07b6d8..edef767e8 100644 --- a/docs/installation-guides/install-zed.md +++ b/docs/installation-guides/install-zed.md @@ -41,6 +41,31 @@ Replace `YOUR_GITHUB_PAT` with your [GitHub Personal Access Token](https://githu The local GitHub MCP server runs via Docker and requires Docker Desktop (or another Docker runtime) to be installed and running. +On github.com you can skip the token entirely: the server opens a browser login on first use and keeps the credential in memory only. In Docker, publish a fixed callback port to loopback: + +```json +{ + "context_servers": { + "github": { + "command": "docker", + "args": [ + "run", "-i", "--rm", + "-p", "127.0.0.1:8085:8085", + "-e", "GITHUB_OAUTH_CALLBACK_PORT", + "ghcr.io/github/github-mcp-server" + ], + "env": { + "GITHUB_OAUTH_CALLBACK_PORT": "8085" + } + } + } +} +``` + +See **[Local Server OAuth Login](../oauth-login.md)** for the native-binary flow (no fixed port), headless/device-code fallback, GitHub Enterprise, and bringing your own OAuth or GitHub App. + +To authenticate with a Personal Access Token instead (it takes precedence over OAuth): + ```json { "context_servers": { From 61f70a445284d6235b77d18f6990f56236506f36 Mon Sep 17 00:00:00 2001 From: Sam Morrow Date: Fri, 26 Jun 2026 12:41:54 +0200 Subject: [PATCH 2/3] docs(oauth): correct PKCE/client-secret explanation The previous "How it works" text claimed PKCE removes the need for a client secret. In practice GitHub requires the client secret at the token endpoint for both OAuth Apps and GitHub Apps, and the implementation sends it alongside the PKCE verifier (Manager.oauth2Config populates ClientSecret; flow.go exchanges with VerifierOption). The secret is baked into the distributed binary and is not truly confidential; PKCE is what actually secures the flow. Reword to reflect this accurately. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/oauth-login.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/oauth-login.md b/docs/oauth-login.md index 35989be7b..16c5dab67 100644 --- a/docs/oauth-login.md +++ b/docs/oauth-login.md @@ -32,9 +32,12 @@ pass `--oauth-client-id` (see [Bring your own app](#bring-your-own-app)). The server prefers the **authorization code flow with PKCE**: it starts a loopback callback server on your machine, opens GitHub's authorization page, and -exchanges the returned code for a token. PKCE means the client secret is not -required to complete the exchange, which is why a public, distributed client can -ship without a confidential secret. +exchanges the returned code for a token. GitHub requires a client secret at the +token endpoint (for both OAuth Apps and GitHub Apps), so the exchange sends it +together with the PKCE verifier. Because this is a public, distributed client, +that secret is baked into the binary and is **not truly confidential** — PKCE is +what secures the flow: it binds the authorization code to this one login attempt, +so a code intercepted on the loopback redirect can't be redeemed anywhere else. To present the authorization URL, the server uses the most secure channel your MCP client offers, in order: From 0a562e0804c7b00ec50f3bb677569e422fa265b0 Mon Sep 17 00:00:00 2001 From: Sam Morrow Date: Fri, 26 Jun 2026 12:44:14 +0200 Subject: [PATCH 3/3] docs: don't frame OAuth login as github.com-only MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The intro line said "On github.com you can skip the token entirely", which implied OAuth login only works on github.com. OAuth works on GitHub Enterprise too — you just supply your own app credentials there. Reword to lead with OAuth as the mechanism and scope the zero-config claim correctly: on github.com the official image already includes the app credentials, so the user provides none. Enterprise / bring-your-own-app is covered by the linked OAuth guide. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- README.md | 2 +- docs/installation-guides/install-antigravity.md | 2 +- docs/installation-guides/install-claude.md | 6 +++--- docs/installation-guides/install-cline.md | 2 +- docs/installation-guides/install-codex.md | 2 +- docs/installation-guides/install-copilot-cli.md | 2 +- docs/installation-guides/install-cursor.md | 2 +- docs/installation-guides/install-gemini-cli.md | 2 +- docs/installation-guides/install-opencode.md | 2 +- docs/installation-guides/install-other-copilot-ides.md | 8 ++++---- docs/installation-guides/install-roo-code.md | 2 +- docs/installation-guides/install-windsurf.md | 2 +- docs/installation-guides/install-zed.md | 2 +- 13 files changed, 18 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index bb1791ea4..23c15dc86 100644 --- a/README.md +++ b/README.md @@ -282,7 +282,7 @@ Install in GitHub Copilot on other IDEs (JetBrains, Visual Studio, Eclipse, etc. Add one of the following JSON blocks to your IDE's MCP settings. -**Log in with OAuth (no token to create or store).** On github.com you can start the server with no token at all: it runs a browser-based login on first use and keeps the resulting token **in memory only**. In Docker this needs a fixed callback port published to loopback so the container's login callback is reachable: +**Log in with OAuth (no token to create or store).** On github.com the official image already includes the app credentials, so you provide none yourself: it runs a browser-based login on first use and keeps the resulting token **in memory only**. In Docker this needs a fixed callback port published to loopback so the container's login callback is reachable: ```json { diff --git a/docs/installation-guides/install-antigravity.md b/docs/installation-guides/install-antigravity.md index eced26a82..577ea2471 100644 --- a/docs/installation-guides/install-antigravity.md +++ b/docs/installation-guides/install-antigravity.md @@ -75,7 +75,7 @@ Close and reopen Antigravity for the changes to take effect. If you prefer running the server locally with Docker: -On github.com you can skip the token entirely: the server opens a browser login on first use and keeps the credential in memory only. In Docker, publish a fixed callback port to loopback: +Log in with OAuth instead of a token. On github.com the official image already includes the app credentials, so you provide none yourself — the server opens a browser login on first use and keeps the token in memory only. In Docker, publish a fixed callback port to loopback: ```json { diff --git a/docs/installation-guides/install-claude.md b/docs/installation-guides/install-claude.md index 4374472c0..04658c452 100644 --- a/docs/installation-guides/install-claude.md +++ b/docs/installation-guides/install-claude.md @@ -64,7 +64,7 @@ claude mcp add-json github "{`"type`":`"http`",`"url`":`"https://api.githubcopil ### With Docker -On github.com you can skip the token entirely: the server opens a browser login on first use and keeps the credential in memory only. In Docker, publish a fixed callback port to loopback. Run the following command in the terminal (not in Claude Code CLI): +Log in with OAuth instead of a token. On github.com the official image already includes the app credentials, so you provide none yourself — the server opens a browser login on first use and keeps the token in memory only. In Docker, publish a fixed callback port to loopback. Run the following command in the terminal (not in Claude Code CLI): ```bash claude mcp add github -e GITHUB_OAUTH_CALLBACK_PORT=8085 -- docker run -i --rm -p 127.0.0.1:8085:8085 -e GITHUB_OAUTH_CALLBACK_PORT ghcr.io/github/github-mcp-server @@ -146,7 +146,7 @@ claude mcp add github --transport http https://api.githubcopilot.com/mcp/ -H "Au Add this codeblock to your `claude_desktop_config.json`: -On github.com you can skip the token entirely: the server opens a browser login on first use and keeps the credential in memory only. In Docker, publish a fixed callback port to loopback: +Log in with OAuth instead of a token. On github.com the official image already includes the app credentials, so you provide none yourself — the server opens a browser login on first use and keeps the token in memory only. In Docker, publish a fixed callback port to loopback: ```json { @@ -251,7 +251,7 @@ Or open the file in a text editor and add the `mcpServers` block manually: > **macOS note**: Xcode runs with a minimal `PATH` that typically excludes `/usr/local/bin` (Intel) and `/opt/homebrew/bin` (Apple Silicon). Use the full path to `docker` to ensure it can be found. Run `which docker` in Terminal to find the correct path on your system. -On github.com you can skip the token entirely: the server opens a browser login on first use and keeps the credential in memory only. In Docker, publish a fixed callback port to loopback: +Log in with OAuth instead of a token. On github.com the official image already includes the app credentials, so you provide none yourself — the server opens a browser login on first use and keeps the token in memory only. In Docker, publish a fixed callback port to loopback: ```json { diff --git a/docs/installation-guides/install-cline.md b/docs/installation-guides/install-cline.md index fd11d51e6..25131c210 100644 --- a/docs/installation-guides/install-cline.md +++ b/docs/installation-guides/install-cline.md @@ -31,7 +31,7 @@ Replace `YOUR_GITHUB_PAT` with your [GitHub Personal Access Token](https://githu 1. Click the Cline icon in your editor's sidebar (or open the command palette and search for "Cline"), then click the **MCP Servers** icon (server stack icon at the top of the Cline panel), and click **"Configure MCP Servers"** to open `cline_mcp_settings.json`. 2. Add one of the configurations below. The OAuth option needs no token; for the PAT option, replace `YOUR_GITHUB_PAT` with your [GitHub Personal Access Token](https://github.com/settings/tokens). -On github.com you can skip the token entirely: the server opens a browser login on first use and keeps the credential in memory only. In Docker, publish a fixed callback port to loopback: +Log in with OAuth instead of a token. On github.com the official image already includes the app credentials, so you provide none yourself — the server opens a browser login on first use and keeps the token in memory only. In Docker, publish a fixed callback port to loopback: ```json { diff --git a/docs/installation-guides/install-codex.md b/docs/installation-guides/install-codex.md index e06737c93..9336a26d7 100644 --- a/docs/installation-guides/install-codex.md +++ b/docs/installation-guides/install-codex.md @@ -47,7 +47,7 @@ echo -e ".env" >> .gitignore Use this if you prefer a local, self-hosted instance instead of the remote HTTP server. See the [OpenAI documentation for configuration](https://developers.openai.com/codex/mcp) for the authoritative schema. -On github.com you can skip the token entirely: the server opens a browser login on first use and keeps the credential in memory only. In Docker, publish a fixed callback port to loopback: +Log in with OAuth instead of a token. On github.com the official image already includes the app credentials, so you provide none yourself — the server opens a browser login on first use and keeps the token in memory only. In Docker, publish a fixed callback port to loopback: ```toml [mcp_servers.github] diff --git a/docs/installation-guides/install-copilot-cli.md b/docs/installation-guides/install-copilot-cli.md index 7249e0331..4ae9d0efe 100644 --- a/docs/installation-guides/install-copilot-cli.md +++ b/docs/installation-guides/install-copilot-cli.md @@ -95,7 +95,7 @@ For additional options like toolsets and read-only mode, see the [remote server With Docker running, you can run the GitHub MCP server in a container: -On github.com you can skip the token entirely: the server opens a browser login on first use and keeps the credential in memory only. In Docker, publish a fixed callback port to loopback: +Log in with OAuth instead of a token. On github.com the official image already includes the app credentials, so you provide none yourself — the server opens a browser login on first use and keeps the token in memory only. In Docker, publish a fixed callback port to loopback: ```json { diff --git a/docs/installation-guides/install-cursor.md b/docs/installation-guides/install-cursor.md index 305f95bc7..778f1ce19 100644 --- a/docs/installation-guides/install-cursor.md +++ b/docs/installation-guides/install-cursor.md @@ -51,7 +51,7 @@ The local GitHub MCP server runs via Docker and requires Docker Desktop to be in ### Docker Configuration -On github.com you can skip the token entirely: the server opens a browser login on first use and keeps the credential in memory only. In Docker, publish a fixed callback port to loopback: +Log in with OAuth instead of a token. On github.com the official image already includes the app credentials, so you provide none yourself — the server opens a browser login on first use and keeps the token in memory only. In Docker, publish a fixed callback port to loopback: ```json { diff --git a/docs/installation-guides/install-gemini-cli.md b/docs/installation-guides/install-gemini-cli.md index 7c5d82927..5bc738968 100644 --- a/docs/installation-guides/install-gemini-cli.md +++ b/docs/installation-guides/install-gemini-cli.md @@ -61,7 +61,7 @@ You can also connect to the hosted MCP server directly. After securely storing y With docker running, you can run the GitHub MCP server in a container. -On github.com you can skip the token entirely: the server opens a browser login on first use and keeps the credential in memory only. In Docker, publish a fixed callback port to loopback: +Log in with OAuth instead of a token. On github.com the official image already includes the app credentials, so you provide none yourself — the server opens a browser login on first use and keeps the token in memory only. In Docker, publish a fixed callback port to loopback: ```json // ~/.gemini/settings.json diff --git a/docs/installation-guides/install-opencode.md b/docs/installation-guides/install-opencode.md index c572f3f8c..ef5949ae6 100644 --- a/docs/installation-guides/install-opencode.md +++ b/docs/installation-guides/install-opencode.md @@ -61,7 +61,7 @@ Set `GITHUB_PERSONAL_ACCESS_TOKEN` in your shell environment before starting Ope The local GitHub MCP server runs via Docker and requires Docker Desktop (or another Docker runtime) to be installed and running. -On github.com you can skip the token entirely: the server opens a browser login on first use and keeps the credential in memory only. In Docker, publish a fixed callback port to loopback: +Log in with OAuth instead of a token. On github.com the official image already includes the app credentials, so you provide none yourself — the server opens a browser login on first use and keeps the token in memory only. In Docker, publish a fixed callback port to loopback: ```json { diff --git a/docs/installation-guides/install-other-copilot-ides.md b/docs/installation-guides/install-other-copilot-ides.md index 9ae9572cb..f4a4d6b5b 100644 --- a/docs/installation-guides/install-other-copilot-ides.md +++ b/docs/installation-guides/install-other-copilot-ides.md @@ -40,7 +40,7 @@ For users who prefer to run the GitHub MCP server locally. Requires Docker insta #### Configuration 1. Create an `.mcp.json` file in your solution or %USERPROFILE% directory. -2. Add this configuration. On github.com you can skip the token entirely: the server opens a browser login on first use and keeps the credential in memory only. In Docker, publish a fixed callback port to loopback: +2. Add this configuration. Log in with OAuth instead of a token. On github.com the official image already includes the app credentials, so you provide none yourself — the server opens a browser login on first use and keeps the token in memory only. In Docker, publish a fixed callback port to loopback: ```json { "servers": { @@ -130,7 +130,7 @@ For users who prefer to run the GitHub MCP server locally. Requires Docker insta #### Configuration -On github.com you can skip the token entirely: the server opens a browser login on first use and keeps the credential in memory only. In Docker, publish a fixed callback port to loopback: +Log in with OAuth instead of a token. On github.com the official image already includes the app credentials, so you provide none yourself — the server opens a browser login on first use and keeps the token in memory only. In Docker, publish a fixed callback port to loopback: ```json { "servers": { @@ -209,7 +209,7 @@ For users who prefer to run the GitHub MCP server locally. Requires Docker insta #### Configuration -On github.com you can skip the token entirely: the server opens a browser login on first use and keeps the credential in memory only. In Docker, publish a fixed callback port to loopback: +Log in with OAuth instead of a token. On github.com the official image already includes the app credentials, so you provide none yourself — the server opens a browser login on first use and keeps the token in memory only. In Docker, publish a fixed callback port to loopback: ```json { "servers": { @@ -289,7 +289,7 @@ For users who prefer to run the GitHub MCP server locally. Requires Docker insta #### Configuration -On github.com you can skip the token entirely: the server opens a browser login on first use and keeps the credential in memory only. In Docker, publish a fixed callback port to loopback: +Log in with OAuth instead of a token. On github.com the official image already includes the app credentials, so you provide none yourself — the server opens a browser login on first use and keeps the token in memory only. In Docker, publish a fixed callback port to loopback: ```json { "servers": { diff --git a/docs/installation-guides/install-roo-code.md b/docs/installation-guides/install-roo-code.md index c3ab25222..dacc68dae 100644 --- a/docs/installation-guides/install-roo-code.md +++ b/docs/installation-guides/install-roo-code.md @@ -33,7 +33,7 @@ To customize toolsets, add server-side headers like `X-MCP-Toolsets` or `X-MCP-R ## Local Server (Docker) -On github.com you can skip the token entirely: the server opens a browser login on first use and keeps the credential in memory only. In Docker, publish a fixed callback port to loopback: +Log in with OAuth instead of a token. On github.com the official image already includes the app credentials, so you provide none yourself — the server opens a browser login on first use and keeps the token in memory only. In Docker, publish a fixed callback port to loopback: ```json { diff --git a/docs/installation-guides/install-windsurf.md b/docs/installation-guides/install-windsurf.md index c19e7b7c2..bbdbc039a 100644 --- a/docs/installation-guides/install-windsurf.md +++ b/docs/installation-guides/install-windsurf.md @@ -30,7 +30,7 @@ Windsurf supports Streamable HTTP servers with a `serverUrl` field: ### Docker Installation (Required) **Important**: The npm package `@modelcontextprotocol/server-github` is no longer supported as of April 2025. Use the official Docker image `ghcr.io/github/github-mcp-server` instead. -On github.com you can skip the token entirely: the server opens a browser login on first use and keeps the credential in memory only. In Docker, publish a fixed callback port to loopback: +Log in with OAuth instead of a token. On github.com the official image already includes the app credentials, so you provide none yourself — the server opens a browser login on first use and keeps the token in memory only. In Docker, publish a fixed callback port to loopback: ```json { diff --git a/docs/installation-guides/install-zed.md b/docs/installation-guides/install-zed.md index edef767e8..88d2cf5ee 100644 --- a/docs/installation-guides/install-zed.md +++ b/docs/installation-guides/install-zed.md @@ -41,7 +41,7 @@ Replace `YOUR_GITHUB_PAT` with your [GitHub Personal Access Token](https://githu The local GitHub MCP server runs via Docker and requires Docker Desktop (or another Docker runtime) to be installed and running. -On github.com you can skip the token entirely: the server opens a browser login on first use and keeps the credential in memory only. In Docker, publish a fixed callback port to loopback: +Log in with OAuth instead of a token. On github.com the official image already includes the app credentials, so you provide none yourself — the server opens a browser login on first use and keeps the token in memory only. In Docker, publish a fixed callback port to loopback: ```json {