github · SamMorrowDrums · Jun 17, 2026
@@ -176,14 +176,15 @@ GitHub Enterprise Server does not support remote server hosting. Please refer to
 
 ## Local GitHub MCP Server
 
-[![Install with Docker in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=github&inputs=%5B%7B%22id%22%3A%22github_token%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22GitHub%20Personal%20Access%20Token%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22-e%22%2C%22GITHUB_PERSONAL_ACCESS_TOKEN%22%2C%22ghcr.io%2Fgithub%2Fgithub-mcp-server%22%5D%2C%22env%22%3A%7B%22GITHUB_PERSONAL_ACCESS_TOKEN%22%3A%22%24%7Binput%3Agithub_token%7D%22%7D%7D) [![Install with Docker in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=github&inputs=%5B%7B%22id%22%3A%22github_token%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22GitHub%20Personal%20Access%20Token%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22-e%22%2C%22GITHUB_PERSONAL_ACCESS_TOKEN%22%2C%22ghcr.io%2Fgithub%2Fgithub-mcp-server%22%5D%2C%22env%22%3A%7B%22GITHUB_PERSONAL_ACCESS_TOKEN%22%3A%22%24%7Binput%3Agithub_token%7D%22%7D%7D&quality=insiders) [![Install with Docker in Visual Studio](https://img.shields.io/badge/Visual_Studio-Install_Server-C16FDE?style=flat-square&logo=visualstudio&logoColor=white)](https://aka.ms/vs/mcp-install?%7B%22name%22%3A%22github%22%2C%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22-e%22%2C%22GITHUB_PERSONAL_ACCESS_TOKEN%22%2C%22ghcr.io%2Fgithub%2Fgithub-mcp-server%22%5D%7D)
+[![Install with Docker in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=github&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22-p%22%2C%22127.0.0.1%3A8085%3A8085%22%2C%22-e%22%2C%22GITHUB_OAUTH_CALLBACK_PORT%22%2C%22ghcr.io%2Fgithub%2Fgithub-mcp-server%22%5D%2C%22env%22%3A%7B%22GITHUB_OAUTH_CALLBACK_PORT%22%3A%228085%22%7D%7D) [![Install with Docker in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=github&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22-p%22%2C%22127.0.0.1%3A8085%3A8085%22%2C%22-e%22%2C%22GITHUB_OAUTH_CALLBACK_PORT%22%2C%22ghcr.io%2Fgithub%2Fgithub-mcp-server%22%5D%2C%22env%22%3A%7B%22GITHUB_OAUTH_CALLBACK_PORT%22%3A%228085%22%7D%7D&quality=insiders) [![Install with Docker in Visual Studio](https://img.shields.io/badge/Visual_Studio-Install_Server-C16FDE?style=flat-square&logo=visualstudio&logoColor=white)](https://aka.ms/vs/mcp-install?%7B%22name%22%3A%22github%22%2C%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22-p%22%2C%22127.0.0.1%3A8085%3A8085%22%2C%22-e%22%2C%22GITHUB_OAUTH_CALLBACK_PORT%3D8085%22%2C%22ghcr.io%2Fgithub%2Fgithub-mcp-server%22%5D%7D)
 
 ### Prerequisites
 
 1. To run the server in a container, you will need to have [Docker](https://www.docker.com/) installed.
 2. Once Docker is installed, you will also need to ensure Docker is running. The Docker image is available at `ghcr.io/github/github-mcp-server`. The image is public; if you get errors on pull, you may have an expired token and need to `docker logout ghcr.io`.
-3. Lastly you will need to [Create a GitHub Personal Access Token](https://github.com/settings/personal-access-tokens/new).
-The MCP server can use many of the GitHub APIs, so enable the permissions that you feel comfortable granting your AI tools (to learn more about access tokens, please check out the [documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)).
+3. **Authentication.** On github.com you don't need to create anything up front — the one-click buttons above log you in with OAuth on first use (a browser-based flow; the token is kept in memory only). The Docker buttons publish a fixed callback port (`127.0.0.1:8085`) so the container's login callback is reachable. See **[Local Server OAuth Login](docs/oauth-login.md)** for how it works, headless/device-code fallback, and bringing your own OAuth or GitHub App (required for GitHub Enterprise Server and `ghe.com`).
+
+   Prefer a token? You can still authenticate with a [GitHub Personal Access Token](https://github.com/settings/personal-access-tokens/new) by setting `GITHUB_PERSONAL_ACCESS_TOKEN` instead (it takes precedence over OAuth). The MCP server can use many of the GitHub APIs, so enable the permissions that you feel comfortable granting your AI tools (to learn more about access tokens, please check out the [documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)).
 
 <details><summary><b>Handling PATs Securely</b></summary>
 
@@ -281,6 +282,8 @@ Install in GitHub Copilot on other IDEs (JetBrains, Visual Studio, Eclipse, etc.
 
 Add the following JSON block 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.
+
 ```json
 {
   "mcp": {

@@ -0,0 +1,263 @@
+# Local Server OAuth Login (stdio)
+
+The local (stdio) GitHub MCP Server can log you in with OAuth instead of a
+Personal Access Token (PAT). On first use it walks you through GitHub's
+authorization flow in your browser and keeps the resulting token **in memory
+only** — nothing is written to disk.
+
+Official released binaries and the `ghcr.io/github/github-mcp-server` image ship
+with a registered GitHub OAuth application baked in, so on **github.com** you can
+start the server with no token and no client ID at all. To target a different
+host (GitHub Enterprise Server or `ghe.com`), or to use your own application,
+pass `--oauth-client-id` (see [Bring your own app](#bring-your-own-app)).
+
+> OAuth login applies to the **stdio** server only. The remote server and the
+> `http` command have their own authentication; see
+> [Remote Server](remote-server.md).
+
+## Contents
+
+- [How it works](#how-it-works)
+- [Quick start](#quick-start)
+- [Configuration reference](#configuration-reference)
+- [Scope filtering](#scope-filtering)
+- [Running in Docker](#running-in-docker)
+- [Headless and device-code fallback](#headless-and-device-code-fallback)
+- [URL elicitation and the security advisory](#url-elicitation-and-the-security-advisory)
+- [Bring your own app](#bring-your-own-app)
+- [GitHub Enterprise Server and ghe.com](#github-enterprise-server-and-ghecom)
+- [Building from source with baked-in credentials](#building-from-source-with-baked-in-credentials)
+
+## How it works
+
+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.
+
+To present the authorization URL, the server uses the most secure channel your
+MCP client offers, in order:
+
+1. **Open your browser automatically** (native runs).
+2. **URL elicitation** — the client prompts you with the link out of band, so the
+   URL never enters the model's context. Requires a client that supports MCP
+   elicitation (e.g. VS Code 1.101+).
+3. **A message in the first tool response** — a last resort for clients without
+   elicitation. This includes a [security advisory](#url-elicitation-and-the-security-advisory).
+
+If the authorization-code flow can't be used — for example, a container with no
+published callback port — the server falls back to the
+[device-code flow](#headless-and-device-code-fallback).
+
+GitHub App tokens that expire are refreshed transparently using the refresh
+token, so long-running sessions keep working without re-authorizing.
+
+## Quick start
+
+**Native binary (recommended).** Best experience: a random loopback port is
+used and your browser opens automatically. On github.com with an official build,
+no flags are needed:
+
+```bash
+github-mcp-server stdio
+```
+
+With your own application:
+
+```bash
+github-mcp-server stdio --oauth-client-id <YOUR_CLIENT_ID>
+```
+
+VS Code (`.vscode/mcp.json`), using your own app:
+
+```json
+{
+  "servers": {
+    "github": {
+      "command": "/path/to/github-mcp-server",
+      "args": ["stdio", "--oauth-client-id", "<YOUR_CLIENT_ID>"]
+    }
+  }
+}
+```
+
+For Docker, see [Running in Docker](#running-in-docker) — containers need a fixed
+callback port.
+
+## Configuration reference
+
+OAuth login is configured with these stdio flags (each has an environment
+variable equivalent). Flags apply only to the `stdio` command.
+
+| Flag | Environment variable | Description |
+|------|----------------------|-------------|
+| `--oauth-client-id` | `GITHUB_OAUTH_CLIENT_ID` | OAuth App or GitHub App client ID. Enables OAuth login when no token is set. Defaults to the baked-in app on github.com for official builds. |
+| `--oauth-client-secret` | `GITHUB_OAUTH_CLIENT_SECRET` | Client secret, **if your app requires one**. For distributed clients this is a public, non-confidential credential. |
+| `--oauth-scopes` | `GITHUB_OAUTH_SCOPES` | Comma-separated scopes to request. Also [filters tools](#scope-filtering) to those scopes. Defaults to the full supported set. |
+| `--oauth-callback-port` | `GITHUB_OAUTH_CALLBACK_PORT` | Fixed local port for the callback server. Defaults to a random port; set a fixed port when mapping it through Docker. |
+
+A static token still takes precedence: if `GITHUB_PERSONAL_ACCESS_TOKEN` is set,
+the server uses it and skips OAuth entirely.
+
+## Scope filtering
+
+The scopes you request determine which tools are exposed. Requesting the full
+supported set (the default) hides no tools. Narrowing `--oauth-scopes` both
+narrows the token's grant **and** filters out tools that would need a scope you
+didn't request, so the tool list reflects what the token can actually do.
+
+For example, requesting only `repo,read:org` hides tools that require `gist`,
+`workflow`, `notifications`, and so on.
+
+## Running in Docker
+
+A container can't reach a random loopback port on your host, so Docker OAuth
+needs a **fixed** callback port that you publish into the container. Use port
+**8085** to match the official app's registered callback URL.
+
+```bash
+docker run -i --rm \
+  -p 127.0.0.1:8085:8085 \
+  -e GITHUB_OAUTH_CALLBACK_PORT=8085 \
+  ghcr.io/github/github-mcp-server
+```
+
+VS Code (`.vscode/mcp.json`):
+
+```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" }
+    }
+  }
+}
+```
+
+Because the container can't open your host browser, the authorization URL
+arrives via [URL elicitation](#url-elicitation-and-the-security-advisory) or the
+tool-response message. After you authorize, your browser hits
+`localhost:8085`, which Docker forwards into the container's callback.
+
+If you bring your own app for Docker, register its callback URL as exactly
+`http://localhost:8085/callback`.
+
+> **Two safety properties to be aware of with a fixed port:**
+>
+> - **Publish to loopback only** (`-p 127.0.0.1:8085:8085`, not `-p 8085:8085`).
+>   Inside a container the callback necessarily listens on all interfaces, so a
+>   plain publish would expose the authorization code to your network. The
+>   server logs a warning reminding you of this when it binds inside a container.
+> - **A busy port is fatal, by design.** With a fixed port, if the server can't
+>   bind it (another process already holds it), it **stops with an error** rather
+>   than silently falling back to the device flow. A port you didn't get could
+>   belong to another user's process positioned to receive the redirect, so the
+>   server refuses to continue. Free the port or choose a different
+>   `--oauth-callback-port`.
+
+## Headless and device-code fallback
+
+When there's no usable browser or callback — a remote shell, CI, or a container
+started without a published port — the server uses GitHub's **device-code
+flow**. You'll get a short code and a verification URL to open on any device:
+
+```
+Visit https://github.com/login/device and enter the code WDJB-MJHT to authorize
+the GitHub MCP Server.
+```
+
+The server polls GitHub until you finish authorizing, then continues. No
+callback port is involved, so this works anywhere.
+
+## URL elicitation and the security advisory
+
+URL elicitation lets your MCP client present the authorization URL to you
+directly, keeping it **out of the model's context** — the model never sees the
+link or any code embedded in it. This is the most secure way to hand off the
+authorization step.
+
+If your client doesn't support elicitation, the server falls back to placing the
+URL in a tool response and appends a short advisory:
+
+> Note: your MCP client does not appear to support secure URL elicitation. For
+> improved security, consider asking your agent, CLI, or IDE to add it (for
+> example, by opening an issue).
+
+If you see this, your authorization still works — but consider asking your client
+vendor to add elicitation support.
+
+## Bring your own app
+
+You need your own application when targeting a non-github.com host, or when you'd
+rather not use the baked-in app. Either application type works:
+
+- **[Create an OAuth App](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app)** —
+  simplest to set up. Grants the scopes you request.
+- **[Register a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app)** —
+  finer-grained, per-resource permissions and short-lived tokens that refresh
+  automatically. Enable **Device Flow** in the app settings if you want the
+  [headless fallback](#headless-and-device-code-fallback).
+
+When registering, set the authorization callback URL:
+
+- **Native runs** use a random loopback port. For loopback redirects GitHub does
+  not require the callback port to match, so registering
+  `http://localhost/callback` is sufficient.
+- **Docker / fixed port** must match exactly: register
+  `http://localhost:8085/callback` (or whichever port you publish).
+
+Then pass the client ID (and secret, only if your app requires one):
+
+```bash
+github-mcp-server stdio \
+  --oauth-client-id <YOUR_CLIENT_ID> \
+  --oauth-client-secret <YOUR_CLIENT_SECRET>
+```
+
+## GitHub Enterprise Server and ghe.com
+
+The baked-in app is registered on github.com only, so it is **not** used when you
+set a custom host. GitHub Enterprise Server and `ghe.com` (Enterprise Cloud with
+data residency) users must **bring their own app** registered on that host and
+pass `--oauth-client-id`.
+
+Set the host with `--gh-host` / `GITHUB_HOST`; the server derives the OAuth
+authorization, token, and device endpoints from it, so login is directed at your
+instance's authorization server rather than github.com:
+
+```bash
+github-mcp-server stdio \
+  --gh-host https://github.example.com \
+  --oauth-client-id <YOUR_CLIENT_ID>
+```
+
+- For GitHub Enterprise Server, prefix the host with `https://`.
+- For `ghe.com`, use `https://YOURSUBDOMAIN.ghe.com`.
+
+Register the app's callback URL on the same host (e.g.
+`http://localhost/callback` for native runs, or `http://localhost:8085/callback`
+for Docker).
+
+## Building from source with baked-in credentials
+
+Official builds embed the default OAuth client via linker flags at build time, so
+they are not present in the source tree. To produce your own build with embedded
+credentials, set them with `-ldflags`:
+
+```bash
+go build -ldflags "\
+  -X github.com/github/github-mcp-server/internal/buildinfo.OAuthClientID=<CLIENT_ID> \
+  -X github.com/github/github-mcp-server/internal/buildinfo.OAuthClientSecret=<CLIENT_SECRET>" \
+  ./cmd/github-mcp-server
+```
+
+Without these, a source build simply has no baked-in app and expects
+`--oauth-client-id` (or a PAT) at runtime.
@@ -16,15 +16,27 @@
         "type": "stdio"
       },
       "runtimeArguments": [
+        {
+          "type": "named",
+          "name": "-p",
+          "description": "Publish the OAuth callback port to loopback so the in-container login callback is reachable",
+          "value": "127.0.0.1:8085:8085"
+        },
+        {
+          "type": "named",
+          "name": "-e",
+          "description": "Fixed OAuth callback port, matching the published port above",
+          "value": "GITHUB_OAUTH_CALLBACK_PORT=8085"
+        },
         {
           "type": "named",
           "name": "-e",
-          "description": "Set an environment variable in the runtime",
+          "description": "Optional GitHub Personal Access Token. Omit to log in with OAuth on first use.",
           "value": "GITHUB_PERSONAL_ACCESS_TOKEN={token}",
-          "isRequired": true,
+          "isRequired": false,
           "variables": {
             "token": {
-              "isRequired": true,
+              "isRequired": false,
               "isSecret": true,
               "format": "string"
             }