Pod to App: Codex
How to install the GitHub MCP server in Codex
By Sophie Filer · Updated 11 Nov 2026 · Steps checked against GitHub's own docs on 11 Nov 2026
The short answer
Put your GitHub token in an environment variable called GITHUB_PAT_TOKEN, then run the command below. Codex reads the token from that variable on every start, so the token itself never sits in a config file.
codex mcp add github --url https://api.githubcopilot.com/mcp/ --bearer-token-env-var GITHUB_PAT_TOKEN- Config file
- ~/.codex/config.toml
- Sign-in
- Token via environment variable
- Covers
- Codex CLI and IDE extension
- Price
- Free, no Copilot needed
Before you start
- Codex installed, as the CLI or the IDE extension. Both read the same
~/.codex/config.toml, so one setup covers both. - A GitHub personal access token from GitHub's token page.
- A place to keep the token as an environment variable: your shell profile, or a
.envfile that is listed in.gitignore.
Install it step by step
- Step 1: Create the token and export it, for example
export GITHUB_PAT_TOKEN=github_pat_...in your shell profile. Open a new terminal so it is set. - Step 2: Run the
codex mcp addcommand at the top of this page. The--bearer-token-env-varflag is required for token sign-in on the hosted server. - Step 3: Start Codex. In the CLI, type
/mcp; in the IDE, open the MCP panel. github should be listed with its tools. - Step 4: Ask: "List my GitHub repositories" to confirm it can reach your account.
The same thing in config.toml
The command just writes a table to your Codex config. You can add it by hand instead:
[mcp_servers.github]
url = "https://api.githubcopilot.com/mcp/"
bearer_token_env_var = "GITHUB_PAT_TOKEN"Which token scopes Codex needs
GitHub's Codex guide suggests starting small and adding scopes only when a tool call fails for lack of permission:
| Scope | Unlocks |
|---|---|
repo | Everyday repository, issue and pull request work |
workflow | Reading and triggering GitHub Actions workflows |
read:org | Organisation-level information |
gist | Creating and listing gists |
project | Classic project boards |
Run it locally with Docker
With Docker you can skip the token: GitHub's image opens a browser login the first time and keeps the result only in memory. It needs a fixed port for the login callback:
[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" }If it does not work
| What you see | What to do |
|---|---|
github is not listed in /mcp | The table name must be exactly [mcp_servers.github]. A typo or broken TOML hides it. |
| 401 Unauthorized | The token expired or was revoked, or the variable is empty in the shell that started Codex. Run echo $GITHUB_PAT_TOKEN to check. |
| Listed, but zero tools | The token lacks scopes. Add repo first, then others as needed. |
| Token committed by mistake | Revoke it on GitHub straight away, make a new one, and add the file to .gitignore. |
MCP Shelf take
Is GitHub worth adding to Codex?
Codex is already good at changing code in your checkout; this server lets it see the GitHub side of the job, such as issues, pull requests, Actions runs and gists. The environment-variable approach is the right default here, and nicer than pasting tokens into JSON as other apps make you do. If you already use the gh command line tool in your terminal, try asking Codex to use that first: for simple tasks it may be enough. Add the MCP server when you want structured access to issues and reviews.
Sophie Filer
Questions
Does the GitHub MCP server work in both the Codex CLI and the IDE extension?
Yes. They share ~/.codex/config.toml, so adding the server once makes it available in both.
Where do I put my GitHub token for Codex?
In an environment variable, such as GITHUB_PAT_TOKEN. The config only names the variable with bearer_token_env_var, so the secret never lands in the file.
Can Codex sign in to GitHub without a token?
With the hosted server it uses a token. The local Docker image can sign you in through the browser instead, as shown in the Docker section.
Sources: the steps on this page are written in our own words from GitHub's own install docs, install-codex.md, the README. If they disagree with this page, the project's docs win; please tell us from the server page.
