Sam Morrow
fab5fc5ff2
* 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> * 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: don't frame OAuth login as github.com-only 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> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
135 lines
4.9 KiB
Markdown
135 lines
4.9 KiB
Markdown
# Install GitHub MCP Server in OpenAI Codex
|
|
|
|
## Prerequisites
|
|
|
|
1. OpenAI Codex (MCP-enabled) installed / available
|
|
2. A [GitHub Personal Access Token](https://github.com/settings/personal-access-tokens/new)
|
|
|
|
> The remote GitHub MCP server is hosted by GitHub at `https://api.githubcopilot.com/mcp/` and supports Streamable HTTP.
|
|
|
|
## Remote Configuration
|
|
|
|
Edit `~/.codex/config.toml` (shared by CLI and IDE extension) and add:
|
|
|
|
```toml
|
|
[mcp_servers.github]
|
|
url = "https://api.githubcopilot.com/mcp/"
|
|
# Replace with your real PAT (least-privilege scopes). Do NOT commit this.
|
|
bearer_token_env_var = "GITHUB_PAT_TOKEN"
|
|
```
|
|
|
|
You can also add it via the Codex CLI:
|
|
|
|
```bash
|
|
codex mcp add github --url https://api.githubcopilot.com/mcp/ --bearer-token-env-var GITHUB_PAT_TOKEN
|
|
```
|
|
|
|
The `--bearer-token-env-var` option is required for PAT-authenticated access to the hosted GitHub MCP server.
|
|
|
|
<details>
|
|
<summary><b>Storing Your PAT Securely</b></summary>
|
|
<br>
|
|
|
|
For security, avoid hardcoding your token. One common approach:
|
|
|
|
1. Store your token in `.env` file
|
|
```
|
|
GITHUB_PAT_TOKEN=ghp_your_token_here
|
|
```
|
|
|
|
2. Add to .gitignore
|
|
```bash
|
|
echo -e ".env" >> .gitignore
|
|
```
|
|
</details>
|
|
|
|
## Local Docker Configuration
|
|
|
|
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
|
|
|
|
After starting Codex (CLI or IDE):
|
|
1. Run `/mcp` in the TUI or use the IDE MCP panel; confirm `github` shows tools.
|
|
2. Ask: "List my GitHub repositories".
|
|
3. If tools are missing:
|
|
- Check token validity & scopes.
|
|
- Confirm correct table name: `[mcp_servers.github]`.
|
|
|
|
## Usage
|
|
|
|
After setup, Codex can interact with GitHub directly. It will use the default tool set automatically but can be [configured](../../README.md#default-toolset). Try these example prompts:
|
|
|
|
**Repository Operations:**
|
|
- "List my GitHub repositories"
|
|
- "Show me recent issues in [owner/repo]"
|
|
- "Create a new issue in [owner/repo] titled 'Bug: fix login'"
|
|
|
|
**Pull Requests:**
|
|
- "List open pull requests in [owner/repo]"
|
|
- "Show me the diff for PR #123"
|
|
- "Add a comment to PR #123: 'LGTM, approved'"
|
|
|
|
**Actions & Workflows:**
|
|
- "Show me recent workflow runs in [owner/repo]"
|
|
- "Trigger the 'deploy' workflow in [owner/repo]"
|
|
|
|
**Gists:**
|
|
- "Create a gist with this code snippet"
|
|
- "List my gists"
|
|
|
|
> **Tip**: Use `/mcp` in the Codex UI to see all available GitHub tools and their descriptions.
|
|
|
|
## Choosing Scopes for Your PAT
|
|
|
|
Minimal useful scopes (adjust as needed):
|
|
- `repo` (general repository operations)
|
|
- `workflow` (if you want Actions workflow access)
|
|
- `read:org` (if accessing org-level resources)
|
|
- `project` (for classic project boards)
|
|
- `gist` (if using gist tools)
|
|
|
|
Use the principle of least privilege: add scopes only when a tool request fails due to permission.
|
|
|
|
## Troubleshooting
|
|
|
|
| Issue | Possible Cause | Fix |
|
|
|-------|----------------|-----|
|
|
| Authentication failed | Missing/incorrect PAT scope | Regenerate PAT; ensure `repo` scope present |
|
|
| 401 Unauthorized (remote) | Token expired/revoked | Create new PAT; update `bearer_token_env_var` |
|
|
| Server not listed | Wrong table name or syntax error | Use `[mcp_servers.github]`; validate TOML |
|
|
| Tools missing / zero tools | Insufficient PAT scopes | Add needed scopes (workflow, gist, etc.) |
|
|
| Token in file risks leakage | Committed accidentally | Rotate token; add file to `.gitignore` |
|
|
|
|
## Security Best Practices
|
|
1. Never commit tokens into version control
|
|
3. Rotate tokens periodically
|
|
4. Restrict scopes up front; expand only when required
|
|
5. Remove unused PATs from your GitHub account
|
|
|
|
## References
|
|
- Remote server URL: `https://api.githubcopilot.com/mcp/`
|
|
- Release binaries: [GitHub Releases](https://github.com/github/github-mcp-server/releases)
|
|
- OpenAI Codex MCP docs: https://developers.openai.com/codex/mcp
|
|
- Main project README: [Advanced configuration options](../../README.md)
|