# 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. 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: 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 ``` VS Code (`.vscode/mcp.json`), using your own app: ```json { "servers": { "github": { "command": "/path/to/github-mcp-server", "args": ["stdio", "--oauth-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 \ --oauth-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 ``` - 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= \ -X github.com/github/github-mcp-server/internal/buildinfo.OAuthClientSecret=" \ ./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.