Skip to content

Commit 17a449a

Browse files
jamesmontemagnojamesmontemagno
committed
Add installation guide for OpenAI Codex
1 parent dc53810 commit 17a449a

File tree

2 files changed

+247
-0
lines changed

2 files changed

+247
-0
lines changed

‎docs/installation-guides/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ This directory contains detailed installation instructions for the GitHub MCP Se
77
- **[Claude Applications](install-claude.md)** - Installation guide for Claude Web, Claude Desktop and Claude Code CLI
88
- **[Cursor](install-cursor.md)** - Installation guide for Cursor IDE
99
- **[Google Gemini CLI](install-gemini-cli.md)** - Installation guide for Google Gemini CLI
10+
- **[OpenAI Codex](install-codex.md)** - Installation guide for OpenAI Codex
1011
- **[Windsurf](install-windsurf.md)** - Installation guide for Windsurf IDE
1112

1213
## Support by Host Application

‎docs/installation-guides/install-codex.md‎

Lines changed: 246 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,246 @@
1+
# Install GitHub MCP Server in OpenAI Codex
2+
3+
## Prerequisites
4+
5+
1. OpenAI Codex (MCP-enabled) installed / available
6+
2. A [GitHub Personal Access Token](https://github.com/settings/personal-access-tokens/new)
7+
3. (Optional for local hosting) [Docker](https://www.docker.com/) installed and running
8+
9+
<details>
10+
<summary><b>Storing Your PAT Securely</b></summary>
11+
<br>
12+
13+
For security, avoid hardcoding your token. One common approach:
14+
15+
1. Store your token in `.env` file
16+
```
17+
GITHUB_PAT=ghp_your_token_here
18+
```
19+
20+
2. Add to .gitignore
21+
```bash
22+
echo -e ".env\n.codex/config.toml" >> .gitignore
23+
```
24+
25+
</details>
26+
27+
> The remote GitHub MCP server is hosted by GitHub at `https://api.githubcopilot.com/mcp/` and supports Streamable HTTP.
28+
29+
## Quick Remote Configuration (Recommended)
30+
31+
Edit `~/.codex/config.toml` (shared by CLI and IDE extension) and add:
32+
33+
```toml
34+
[mcp_servers.github]
35+
url = "https://api.githubcopilot.com/mcp/"
36+
# Replace with your real PAT (least-privilege scopes). Do NOT commit this.
37+
bearer_token = "ghp_your_token_here"
38+
39+
# Optional server-level timeouts (adjust if tools are long running)
40+
startup_timeout_sec = 30
41+
tool_timeout_sec = 300
42+
```
43+
44+
PAT scopes: start with `repo`; add `workflow`, `read:org`, `project`, `gist` only when needed.
45+
46+
If you prefer not to store the token directly in the file, you can:
47+
1. Use the collapsible "Storing Your PAT Securely" section above for `.env` file approach.
48+
2. Use the Codex IDE extension's config UI to paste it instead of editing the file manually.
49+
3. Regenerate and rotate frequently. (Codex config does not yet support an environment-variable reference for `bearer_token`.)
50+
51+
## Local Docker Configuration (STDIO)
52+
53+
Use this if you prefer a local, self-hosted instance instead of the remote HTTP server.
54+
55+
> The npm package `@modelcontextprotocol/server-github` is deprecated (April 2025). Use the official Docker image `ghcr.io/github/github-mcp-server`.
56+
57+
Add to `config.toml`:
58+
59+
```toml
60+
[mcp_servers.github]
61+
command = "docker"
62+
args = [
63+
"run", "-i", "--rm",
64+
"-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
65+
"ghcr.io/github/github-mcp-server"
66+
]
67+
startup_timeout_sec = 30
68+
tool_timeout_sec = 300
69+
70+
[mcp_servers.github.env]
71+
GITHUB_PERSONAL_ACCESS_TOKEN = "ghp_your_token_here"
72+
```
73+
74+
Or use the Codex CLI to add it (see "Add via Codex CLI" section below).
75+
76+
### Binary (Alternative Local STDIO)
77+
Build the server (or download a release):
78+
79+
```bash
80+
go build -o github-mcp-server ./cmd/github-mcp-server
81+
```
82+
83+
`config.toml` entry:
84+
```toml
85+
[mcp_servers.github]
86+
command = "./github-mcp-server"
87+
args = ["stdio"]
88+
startup_timeout_sec = 30
89+
tool_timeout_sec = 300
90+
91+
[mcp_servers.github.env]
92+
GITHUB_PERSONAL_ACCESS_TOKEN = "ghp_your_token_here"
93+
```
94+
95+
Or use the Codex CLI to add it (see "Add via Codex CLI" section below).
96+
97+
## Add via Codex CLI (STDIO)
98+
99+
The Codex CLI supports adding STDIO MCP servers with `codex mcp add`. This launches the server command when Codex starts. Remote (streamable HTTP) servers like the hosted GitHub MCP (`url = "https://api.githubcopilot.com/mcp/"`) must currently be added by editing `~/.codex/config.toml` directly (the CLI add flow does not set `url`).
100+
101+
### Binary (stdio) via CLI
102+
```bash
103+
export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here
104+
codex mcp add github -- ./github-mcp-server stdio
105+
```
106+
107+
With an inline env flag (alternative):
108+
```bash
109+
codex mcp add github --env GITHUB_PERSONAL_ACCESS_TOKEN=$GITHUB_PERSONAL_ACCESS_TOKEN -- ./github-mcp-server stdio
110+
```
111+
112+
### Docker (stdio) via CLI
113+
```bash
114+
export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here
115+
codex mcp add github -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server
116+
```
117+
118+
Inline env form:
119+
```bash
120+
codex mcp add github --env GITHUB_PERSONAL_ACCESS_TOKEN=$GITHUB_PERSONAL_ACCESS_TOKEN -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server
121+
```
122+
123+
### Verify (CLI)
124+
After adding:
125+
```bash
126+
codex # start Codex TUI
127+
/mcp # list active servers
128+
```
129+
You should see `github` in the list with tools available. If not:
130+
- Re-run with the PAT exported
131+
- Check that the binary is executable: `chmod +x ./github-mcp-server`
132+
- Confirm Docker can pull the image: `docker pull ghcr.io/github/github-mcp-server`
133+
134+
### Removing / Updating
135+
```bash
136+
codex mcp remove github
137+
codex mcp list
138+
```
139+
Then re-add with updated scopes or a rotated token.
140+
141+
## Configuration Details
142+
143+
- **File path**: `~/.codex/config.toml`
144+
- **Scope**: Global configuration shared by both CLI and IDE extension
145+
- **Format**: Must be valid TOML (use a linter to verify)
146+
- **Editor access**:
147+
- CLI: Edit directly or use `codex mcp add` commands
148+
- IDE: Click gear icon → MCP settings → Open config.toml
149+
150+
## Verification
151+
152+
After starting Codex (CLI or IDE):
153+
1. Run `/mcp` in the TUI or use the IDE MCP panel; confirm `github` shows tools.
154+
2. Ask: "List my GitHub repositories".
155+
3. If tools are missing:
156+
- Check token validity & scopes.
157+
- Confirm correct table name: `[mcp_servers.github]`.
158+
- For stdio: ensure env var `GITHUB_PERSONAL_ACCESS_TOKEN` is set before launching Codex.
159+
4. For long-running operations, consider increasing `tool_timeout_sec`.
160+
161+
## Usage
162+
163+
After setup, Codex can interact with GitHub directly. Try these example prompts:
164+
165+
**Repository Operations:**
166+
- "List my GitHub repositories"
167+
- "Show me recent issues in [owner/repo]"
168+
- "Create a new issue in [owner/repo] titled 'Bug: fix login'"
169+
170+
**Pull Requests:**
171+
- "List open pull requests in [owner/repo]"
172+
- "Show me the diff for PR #123"
173+
- "Add a comment to PR #123: 'LGTM, approved'"
174+
175+
**Actions & Workflows:**
176+
- "Show me recent workflow runs in [owner/repo]"
177+
- "Trigger the 'deploy' workflow in [owner/repo]"
178+
179+
**Gists:**
180+
- "Create a gist with this code snippet"
181+
- "List my gists"
182+
183+
> **Tip**: Use `/mcp` in the Codex TUI to see all available GitHub tools and their descriptions.
184+
185+
## Choosing Scopes for Your PAT
186+
187+
Minimal useful scopes (adjust as needed):
188+
- `repo` (general repository operations)
189+
- `workflow` (if you want Actions workflow access)
190+
- `read:org` (if accessing org-level resources)
191+
- `project` (for classic project boards)
192+
- `gist` (if using gist tools)
193+
194+
Use the principle of least privilege: add scopes only when a tool request fails due to permission.
195+
196+
## Troubleshooting
197+
198+
| Issue | Possible Cause | Fix |
199+
|-------|----------------|-----|
200+
| Authentication failed | Missing/incorrect PAT scope | Regenerate PAT; ensure `repo` scope present |
201+
| 401 Unauthorized (remote) | Token expired/revoked | Create new PAT; update `bearer_token` |
202+
| Server not listed | Wrong table name or syntax error | Use `[mcp_servers.github]`; validate TOML |
203+
| Tools missing / zero tools | Insufficient PAT scopes | Add needed scopes (workflow, gist, etc.) |
204+
| Docker run fails | Image pull or local Docker issue | `docker pull ghcr.io/github/github-mcp-server`; verify Docker running |
205+
| Stdio exits immediately | `GITHUB_PERSONAL_ACCESS_TOKEN` not set | Add env table or export var before launch |
206+
| Timeouts on large operations | Default too low | Increase `tool_timeout_sec` (e.g. 600) |
207+
| Token in file risks leakage | Committed accidentally | Rotate token; add file to `.gitignore` |
208+
209+
### Debug Tips
210+
- Mask token: `printf '%s\n' "$GITHUB_PERSONAL_ACCESS_TOKEN" | head -c 4`
211+
- Validate TOML: `python -c 'import tomllib; tomllib.load(open("$HOME/.codex/config.toml","rb"))'`
212+
- Inspect tools: use `/mcp` then expand server details.
213+
- Manual Docker test:
214+
```bash
215+
docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN=$GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server
216+
```
217+
218+
## Security Best Practices
219+
1. Never commit tokens into version control
220+
2. Prefer environment variables or secret managers
221+
3. Rotate tokens periodically
222+
4. Restrict scopes up front; expand only when required
223+
5. Remove unused PATs from your GitHub account
224+
225+
## Important Notes
226+
227+
- **npm package deprecation**: The npm package `@modelcontextprotocol/server-github` is deprecated as of April 2025. Use the official Docker image `ghcr.io/github/github-mcp-server` or build from source.
228+
- **Remote server**: GitHub's hosted MCP server at `https://api.githubcopilot.com/mcp/` is the recommended setup for most users (no Docker needed).
229+
- **Token security**: Never commit `config.toml` with embedded tokens to version control. Use `.gitignore` and rotate tokens regularly.
230+
- **CLI help**: Run `codex mcp --help` to see all available MCP management commands.
231+
- **Configuration sharing**: The `~/.codex/config.toml` file is shared between Codex CLI and IDE extension—configure once, use everywhere.
232+
- **Advanced features**: See the [main README](../../README.md) for toolsets, read-only mode, and dynamic tool discovery options.
233+
234+
## References
235+
- Remote server URL: `https://api.githubcopilot.com/mcp/`
236+
- Docker image: `ghcr.io/github/github-mcp-server`
237+
- Release binaries: [GitHub Releases](https://github.com/github/github-mcp-server/releases)
238+
- OpenAI Codex MCP docs: https://developers.openai.com/codex/mcp
239+
- Main project README: [Advanced configuration options](../../README.md)
240+
241+
## Notes on Host Configuration
242+
Codex MCP server tables live under `[mcp_servers.<name>]`. Supported keys relevant here:
243+
- STDIO: `command`, `args`, `env`, `startup_timeout_sec`, `tool_timeout_sec`
244+
- Streamable HTTP: `url`, `bearer_token`, `startup_timeout_sec`, `tool_timeout_sec`
245+
246+
We intentionally omit OAuth configuration because it requires the experimental RMCP client and is not applicable to the GitHub MCP server in this guide.

0 commit comments

Comments
 (0)