diff --git a/README.md b/README.md index 9be25a4e07..23c15dc86b 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 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 +{ + "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 c24d8e01dc..577ea2471d 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: +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 +{ + "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 d66b34776b..04658c4520 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 + +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 +``` + +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`: +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 +{ + "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. +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 +{ + "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 6bc643cb6a..25131c2105 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). + +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 +{ + "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 af24445882..9336a26d7b 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. + +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] +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 4ac5b3712c..4ae9d0efe7 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: +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 +{ + "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 654f0a7889..778f1ce193 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 +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 +{ + "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 20764384ca..5bc738968a 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. + +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 +{ + "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 10e0e2db2a..ef5949ae66 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. +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 +{ + "$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 a3200179c5..f4a4d6b5b6 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. 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": { + "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 + +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": { + "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 + +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": { + "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 + +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": { + "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 77513fb555..dacc68dae0 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) +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 +{ + "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 8793e2edb9..bbdbc039ab 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. +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 +{ + "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 15bcfde34f..f1c38bad19 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 d0e07b6d8e..88d2cf5eeb 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. +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 +{ + "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": { diff --git a/docs/oauth-login.md b/docs/oauth-login.md index 35989be7b6..16c5dab67e 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: