docs(mcp): update GitHub MCP server guide to use official server#40
docs(mcp): update GitHub MCP server guide to use official server#40
Conversation
dealako
added
the
ai-assisted
WalkthroughReformatted Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
There was a problem hiding this comment.
Pull request overview
Updates the GitHub MCP setup documentation to migrate off the deprecated @modelcontextprotocol/server-github npm package and standardize on the official ghcr.io/github/github-mcp-server (plus a hosted remote HTTP option), while adjusting markdownlint settings to accommodate longer code blocks and tables.
Changes:
- Replaces deprecated npm-based GitHub MCP setup with official server options (remote HTTP, local Docker, binary).
- Updates Cursor AI MCP configuration to use the official Docker image.
- Adds troubleshooting guidance and relaxes markdownlint MD013 for code blocks/tables.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| mcp/github.md | Updates GitHub MCP installation/configuration guidance to use the official server, adds multiple setup paths and troubleshooting. |
| .markdownlint.json | Adjusts MD013 to ignore line length for code blocks and tables. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.markdownlint.json:
- Around line 9-13: The MD013 rule in .markdownlint.json currently disables
enforcement for code_blocks and tables, which lets Markdown lines exceed the
120-character limit; update the MD013 configuration (the "MD013" object) to
enforce line_length for code_blocks and tables (remove the "code_blocks" and
"tables" false entries or set them to true) so Markdown line-length remains
enforced to 120 characters across regular text, code blocks, and tables.
In `@mcp/github.md`:
- Around line 54-55: Wrap the long claude mcp add-json commands to respect the
Markdown line-length policy by breaking after the command and using a shell
line-continuation backslash, e.g., split the invocation for both occurrences of
the claude mcp add-json github and claude mcp add-json --scope user github
examples so the JSON payload starts on the next indented line; ensure you keep
the full JSON string intact, escape nothing further, and maintain the
surrounding triple-backtick bash fences.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: a66c71fc-9a5f-4389-b1e6-30ee914e329e
📒 Files selected for processing (2)
.markdownlint.jsonmcp/github.md
Replace deprecated @modelcontextprotocol/server-github (deprecated April 2025) with the official GitHub MCP server. Add three setup options for Claude Code: remote HTTP endpoint (recommended), local Docker, and binary. Update Cursor AI config to use Docker image. Add troubleshooting section and exempt code blocks and tables from markdownlint line-length checks. Closes: #41 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: David Deal <ddeal@linuxfoundation.org>
dealako
force-pushed
the
feat/github-mcp-updates
branch
from
a972d98 to
ae4aff3
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@mcp/github.md`:
- Around line 5-12: Update the expected output in mcp/claude-context.md where
the list of available MCP servers includes "@modelcontextprotocol/server-github"
(the entry referenced around the current expected-output block, ~line 275): mark
that package as deprecated (add "deprecated as of April 2025") and replace or
augment the entry with the recommended official server reference
"ghcr.io/github/github-mcp-server" and/or the remote hosted endpoint guidance,
ensuring the expected output text matches the deprecation note in mcp/github.md.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 3341ce53-e5dd-4a92-8e02-119cef0f6848
📒 Files selected for processing (2)
.markdownlint.jsonmcp/github.md
🚧 Files skipped from review as they are similar to previous changes (1)
- .markdownlint.json
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
mcp/github.md (1)
54-55:⚠️ Potential issue | 🟡 MinorWrap overlong
claude mcp add-jsoncommand lines.These lines still exceed the Markdown line-length policy and should be split for readability and lint compliance (Line 54, Line 66).
Proposed fix
```bash -claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer $GITHUB_PERSONAL_ACCESS_TOKEN"}}' +claude mcp add-json github \ + '{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer YOUR_GITHUB_PAT"}}'@@
-claude mcp add-json --scope user github '{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer YOUR_GITHUB_PAT"}}' +claude mcp add-json --scope user github \ + '{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer YOUR_GITHUB_PAT"}}'</details> As per coding guidelines, "Keep Markdown line length under 120 characters". Also applies to: 66-67 <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@mcp/github.mdaround lines 54 - 55, The long shell command usages of "claude
mcp add-json" exceed the Markdown line-length policy; split each overlong
command into two lines using a backslash continuation and place the JSON payload
on the next indented line (e.g., for both "claude mcp add-json github" and
"claude mcp add-json --scope user github") and replace the embedded token with a
placeholder like YOUR_GITHUB_PAT to keep lines <120 chars and improve
readability.</details> </blockquote></details> </blockquote></details> <details> <summary>🤖 Prompt for all review comments with AI agents</summary>Verify each finding against the current code and only fix it if needed.
Inline comments:
In@mcp/github.md:
- Around line 50-51: Replace the inconsistent token placeholder usage so Option
1 examples use a single convention: change occurrences of
$GITHUB_PERSONAL_ACCESS_TOKEN to YOUR_GITHUB_PAT (or vice versa if you prefer
env var style) in the three command examples; update the command string that
includes claude mcp add-json github and any adjacent instructive text so all
examples consistently show the same placeholder (e.g., "YOUR_GITHUB_PAT") and
match the explanatory sentence that tells users to replace it.
Duplicate comments:
In@mcp/github.md:
- Around line 54-55: The long shell command usages of "claude mcp add-json"
exceed the Markdown line-length policy; split each overlong command into two
lines using a backslash continuation and place the JSON payload on the next
indented line (e.g., for both "claude mcp add-json github" and "claude mcp
add-json --scope user github") and replace the embedded token with a placeholder
like YOUR_GITHUB_PAT to keep lines <120 chars and improve readability.</details> <details> <summary>🪄 Autofix (Beta)</summary> Fix all unresolved CodeRabbit comments on this PR: - [ ] <!-- {"checkboxId": "4b0d0e0a-96d7-4f10-b296-3a18ea78f0b9"} --> Push a commit to this branch (recommended) - [ ] <!-- {"checkboxId": "ff5b1114-7d8c-49e6-8ac1-43f82af23a33"} --> Create a new PR with the fixes </details> --- <details> <summary>ℹ️ Review info</summary> <details> <summary>⚙️ Run configuration</summary> **Configuration used**: Organization UI **Review profile**: CHILL **Plan**: Pro **Run ID**: `c0ea05fe-c6c5-4c9f-92d4-79bf9b965435` </details> <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between ae4aff3dddcd0f107e73ddf73a22e132a22f2d67 and 5eadb4b035b54df727b4d2066b58a164b6db036e. </details> <details> <summary>📒 Files selected for processing (1)</summary> * `mcp/github.md` </details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
Signed-off-by: David Deal <ddeal@linuxfoundation.org>
dealako
force-pushed
the
feat/github-mcp-updates
branch
from
5eadb4b to
d6ef2ed
Compare
Signed-off-by: David Deal <ddeal@linuxfoundation.org>
There was a problem hiding this comment.
Actionable comments posted: 3
♻️ Duplicate comments (1)
mcp/github.md (1)
48-67:⚠️ Potential issue | 🟡 MinorInconsistent token placeholder naming in Option 1.
Line 50 instructs users to replace
GITHUB_PERSONAL_ACCESS_TOKEN, but line 54 uses$GITHUB_PERSONAL_ACCESS_TOKEN(shell variable expansion syntax), while line 66 usesYOUR_GITHUB_PAT. This creates confusion:
- If users don't export
GITHUB_PERSONAL_ACCESS_TOKENas an environment variable, line 54's command will pass an empty bearer token.- The text and examples should use the same placeholder convention.
🔧 Proposed fix for consistency
-Run the following command, replacing `GITHUB_PERSONAL_ACCESS_TOKEN` with your personal +Run the following command, replacing `YOUR_GITHUB_PAT` with your personal access token: ```bash -claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer $GITHUB_PERSONAL_ACCESS_TOKEN"}}' +claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer YOUR_GITHUB_PAT"}}'</details> As per coding guidelines, documentation should be clear and consistent for users to follow. <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@mcp/github.mdaround lines 48 - 67, Unify the token placeholder usage in the
Option 1 examples: pick a single placeholder name (e.g., YOUR_GITHUB_PAT) and
update every instance of GITHUB_PERSONAL_ACCESS_TOKEN,
$GITHUB_PERSONAL_ACCESS_TOKEN, and YOUR_GITHUB_PAT in the 'claude mcp add-json
github ...' command and the example with --scope to use that single form;
alternatively, if you want to show both literal token and environment variable
usage, provide two clear variants (one using Authorization":"Bearer
YOUR_GITHUB_PAT" and a second using Authorization":"Bearer
$GITHUB_PERSONAL_ACCESS_TOKEN" with a short note to export the env var), and
make the example with --scope user match the chosen variant exactly.</details> </blockquote></details> </blockquote></details> <details> <summary>🧹 Nitpick comments (2)</summary><blockquote> <details> <summary>mcp/github.md (2)</summary><blockquote> `143-154`: **Consider adding cross-platform keyboard shortcuts.** Line 152 mentions `CMD+I` for macOS, but doesn't include the Windows/Linux equivalent (`Ctrl+I`). Since Cursor AI is cross-platform, documenting both shortcuts improves accessibility. <details> <summary>🖥️ Proposed enhancement</summary> ```diff Additionally, you can generate a prompt to inquire about a specific GitHub pull request, issue, or repository. See the Validation section below for an -example. Hit `CMD+I` to open the AI assistant within Cursor and enter a prompt +example. Hit `CMD+I` (macOS) or `Ctrl+I` (Windows/Linux) to open the AI assistant within Cursor and enter a prompt to query GitHub (see [Validation section below](`#validation`)).🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@mcp/github.md` around lines 143 - 154, The doc currently only lists the macOS shortcut "CMD+I" for opening the AI assistant; update the text in the paragraph that mentions "Hit `CMD+I` to open the AI assistant within Cursor" to include cross-platform equivalents (e.g., "CMD+I (macOS) / Ctrl+I (Windows/Linux)") so users on all platforms see the correct shortcut; ensure the same change is reflected wherever "CMD+I" appears (e.g., the Validation section and the "Open MCP Settings" guidance) to keep shortcuts consistent across the MCP setup documentation.
183-187: Clarify when Docker logout is needed.Line 187 suggests running
docker logout ghcr.ioto clear stored credentials, but this may confuse users:
- The
ghcr.io/github/github-mcp-serverimage is public and doesn't require authentication to pull.- Most users won't have credentials cached for ghcr.io unless they've explicitly logged in.
- Logging out would only help if invalid/expired credentials are cached and preventing access.
📝 Proposed clarification
**Docker Issues:** - Confirm Docker Desktop is running. - Pull the image manually: `docker pull ghcr.io/github/github-mcp-server` -- Log out from GitHub Container Registry (clears stored credentials): `docker logout ghcr.io` +- If you have cached credentials that may be invalid, clear them: `docker logout ghcr.io`🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@mcp/github.md` around lines 183 - 187, Clarify that the image ghcr.io/github/github-mcp-server is public so authentication is not normally required, and update the Docker Issues section to say to only run the command `docker logout ghcr.io` if you have previously logged into ghcr.io and are troubleshooting failed pulls due to cached/expired credentials; mention that most users can skip the logout step unless they explicitly logged in or see authentication errors when pulling the image.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@mcp/github.md`:
- Around line 57-67: Add a security warning near the description of the
--scope/project behavior (.mcp.json) to warn users not to store secrets or
personal access tokens in project-scoped configs because they may be committed
to version control; instruct them to prefer --scope user or --scope local for
tokens, to use environment variables or a secret manager instead of embedding
Authorization headers in JSON, and to use placeholders in example commands
(e.g., YOUR_GITHUB_PAT) and mention adding .mcp.json to .gitignore if
project-scoped secrets are unavoidable.
- Around line 121-141: The Cursor AI config under mcpServers -> "github" uses
the placeholder "YOUR_PERSONAL_ACCESS_TOKEN" for the
GITHUB_PERSONAL_ACCESS_TOKEN env value which is inconsistent with other examples
that use "YOUR_GITHUB_PAT"; update the placeholder value to "YOUR_GITHUB_PAT"
(both in the env object and any example strings) so the "mcpServers", "github",
and "GITHUB_PERSONAL_ACCESS_TOKEN" entries match the Claude Code examples and
avoid confusion.
- Around line 72-80: Clarify the placeholder usage in the Option 2 example:
update the text around the command that includes "claude mcp add github -e
GITHUB_PERSONAL_ACCESS_TOKEN=YOUR_GITHUB_PAT -- \ docker run -i --rm -e
GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server" to state
explicitly that users can either (A) replace YOUR_GITHUB_PAT with their literal
token in the claude mcp command, or (B) export GITHUB_PERSONAL_ACCESS_TOKEN in
their shell first and then omit the value (i.e., use -e
GITHUB_PERSONAL_ACCESS_TOKEN without =VALUE so Docker inherits the parent
environment); mention both alternatives and show which form of the -e flag
corresponds to each approach.
---
Duplicate comments:
In `@mcp/github.md`:
- Around line 48-67: Unify the token placeholder usage in the Option 1 examples:
pick a single placeholder name (e.g., YOUR_GITHUB_PAT) and update every instance
of GITHUB_PERSONAL_ACCESS_TOKEN, $GITHUB_PERSONAL_ACCESS_TOKEN, and
YOUR_GITHUB_PAT in the 'claude mcp add-json github ...' command and the example
with --scope to use that single form; alternatively, if you want to show both
literal token and environment variable usage, provide two clear variants (one
using Authorization":"Bearer YOUR_GITHUB_PAT" and a second using
Authorization":"Bearer $GITHUB_PERSONAL_ACCESS_TOKEN" with a short note to
export the env var), and make the example with --scope user match the chosen
variant exactly.
---
Nitpick comments:
In `@mcp/github.md`:
- Around line 143-154: The doc currently only lists the macOS shortcut "CMD+I"
for opening the AI assistant; update the text in the paragraph that mentions
"Hit `CMD+I` to open the AI assistant within Cursor" to include cross-platform
equivalents (e.g., "CMD+I (macOS) / Ctrl+I (Windows/Linux)") so users on all
platforms see the correct shortcut; ensure the same change is reflected wherever
"CMD+I" appears (e.g., the Validation section and the "Open MCP Settings"
guidance) to keep shortcuts consistent across the MCP setup documentation.
- Around line 183-187: Clarify that the image ghcr.io/github/github-mcp-server
is public so authentication is not normally required, and update the Docker
Issues section to say to only run the command `docker logout ghcr.io` if you
have previously logged into ghcr.io and are troubleshooting failed pulls due to
cached/expired credentials; mention that most users can skip the logout step
unless they explicitly logged in or see authentication errors when pulling the
image.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
| Use the `--scope` flag to control where the configuration is stored: | ||
|
|
||
| - `--scope local` — current project only (default) | ||
| - `--scope project` — shared with the team via `.mcp.json` | ||
| - `--scope user` — all projects on this machine | ||
|
|
||
| Example with user scope: | ||
|
|
||
| ```bash | ||
| claude mcp add-json --scope user github '{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer YOUR_GITHUB_PAT"}}' | ||
| ``` |
There was a problem hiding this comment.
Security risk: tokens in --scope project configurations.
Line 60 indicates that --scope project shares the configuration with the team via .mcp.json, which is typically version-controlled. Since the configuration in lines 54-66 embeds the personal access token directly in the JSON (in the Authorization header), using --scope project would commit the token to the repository, exposing it to all team members and potentially in git history.
📋 Recommended documentation addition
Add a security warning after line 61:
- `--scope project` — shared with the team via `.mcp.json`
- `--scope user` — all projects on this machine
+
+> **Security Warning:** When using `--scope project`, the token will be stored
+> in `.mcp.json` which may be version-controlled. Never commit personal access
+> tokens to version control. Use `--scope user` or `--scope local` for token-based
+> configurations.
Example with user scope:🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@mcp/github.md` around lines 57 - 67, Add a security warning near the
description of the --scope/project behavior (.mcp.json) to warn users not to
store secrets or personal access tokens in project-scoped configs because they
may be committed to version control; instruct them to prefer --scope user or
--scope local for tokens, to use environment variables or a secret manager
instead of embedding Authorization headers in JSON, and to use placeholders in
example commands (e.g., YOUR_GITHUB_PAT) and mention adding .mcp.json to
.gitignore if project-scoped secrets are unavoidable.
| ### Option 2: Local Docker Deployment | ||
|
|
||
| If you prefer to run the server locally, ensure Docker is installed and running, | ||
| then execute: | ||
|
|
||
| ```bash | ||
| claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=YOUR_GITHUB_PAT -- \ | ||
| docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server | ||
| ``` |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Clarify placeholder replacement for Option 2.
Line 78 uses YOUR_GITHUB_PAT as a placeholder, but it's unclear whether users should:
- Replace it with their literal token value
- Export it as an environment variable first
- Use a different approach
Given that Docker's -e GITHUB_PERSONAL_ACCESS_TOKEN (without a value) inherits from the parent environment, users must replace YOUR_GITHUB_PAT with their literal token in the claude mcp add command.
📝 Proposed clarification
### Option 2: Local Docker Deployment
If you prefer to run the server locally, ensure Docker is installed and running,
-then execute:
+then execute the following command, replacing `YOUR_GITHUB_PAT` with your personal
+access token:
```bash
claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=YOUR_GITHUB_PAT -- \
docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
Verify each finding against the current code and only fix it if needed.
In @mcp/github.md around lines 72 - 80, Clarify the placeholder usage in the
Option 2 example: update the text around the command that includes "claude mcp
add github -e GITHUB_PERSONAL_ACCESS_TOKEN=YOUR_GITHUB_PAT -- \ docker run -i
--rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server" to state
explicitly that users can either (A) replace YOUR_GITHUB_PAT with their literal
token in the claude mcp command, or (B) export GITHUB_PERSONAL_ACCESS_TOKEN in
their shell first and then omit the value (i.e., use -e
GITHUB_PERSONAL_ACCESS_TOKEN without =VALUE so Docker inherits the parent
environment); mention both alternatives and show which form of the -e flag
corresponds to each approach.
</details>
<!-- fingerprinting:phantom:triton:puma:bd8739bf-b4b2-40c3-87b8-b6bdc372b46c -->
<!-- This is an auto-generated comment by CodeRabbit -->
| ```jsonc | ||
| { | ||
| // ... | ||
| "mcpServers": { | ||
| "github": { | ||
| "command": "npx", | ||
| "command": "docker", | ||
| "args": [ | ||
| "-y", | ||
| "@modelcontextprotocol/server-github" | ||
| "run", | ||
| "-i", | ||
| "--rm", | ||
| "-e", | ||
| "GITHUB_PERSONAL_ACCESS_TOKEN", | ||
| "ghcr.io/github/github-mcp-server", | ||
| ], | ||
| "env": { | ||
| "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_PERSONAL_ACCESS_TOKEN" | ||
| } | ||
| } | ||
| } | ||
| "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_PERSONAL_ACCESS_TOKEN", | ||
| }, | ||
| }, | ||
| }, | ||
| } | ||
| ``` |
There was a problem hiding this comment.
Inconsistent token placeholder in Cursor AI configuration.
Line 136 uses YOUR_PERSONAL_ACCESS_TOKEN, while all Claude Code examples use YOUR_GITHUB_PAT (lines 66, 78, 89). This inconsistency can confuse users who are setting up both tools.
🔧 Proposed fix for consistency
"env": {
- "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_PERSONAL_ACCESS_TOKEN",
+ "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT",
},As per coding guidelines, documentation should maintain consistency for clarity.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@mcp/github.md` around lines 121 - 141, The Cursor AI config under mcpServers
-> "github" uses the placeholder "YOUR_PERSONAL_ACCESS_TOKEN" for the
GITHUB_PERSONAL_ACCESS_TOKEN env value which is inconsistent with other examples
that use "YOUR_GITHUB_PAT"; update the placeholder value to "YOUR_GITHUB_PAT"
(both in the env object and any example strings) so the "mcpServers", "github",
and "GITHUB_PERSONAL_ACCESS_TOKEN" entries match the Claude Code examples and
avoid confusion.
Closes #41
Summary
@modelcontextprotocol/server-githubnpm package (deprecated April 2025) with the officialghcr.io/github/github-mcp-serverimage.markdownlint.jsonto exempt code blocks and tables from the line-length rule (MD013)Related Issues
Test plan
markdownlint mcp/github.mdpasses with no errorsclaude mcp listandclaude mcp get githubreturn expected output after setup🤖 Generated with Claude Code