Skip to content

docs(mcp): update GitHub MCP server guide to use official server #40

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dealako wants to merge 4 commits into
base: main
Choose a base branch
from
+174 −64
Open

docs(mcp): update GitHub MCP server guide to use official server #40

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ae4aff3
docs(mcp): update GitHub MCP server guide to use official server
dealako Mar 30, 2026
4af864e
Addressed additional review feedback
dealako Mar 30, 2026
83bb848
docs(mcp): address review feedback on GitHub MCP guide
dealako Apr 1, 2026
08f08c9
Merge branch 'main' into feat/github-mcp-updates
dealako Apr 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 15 additions & 5 deletions .markdownlint.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,19 @@
{
"default": true,
"MD003": { "style": "atx" },
"MD007": { "indent": 2 },
"MD013": { "line_length": 120, "code_blocks": false, "tables": false },
"MD024": { "allow_different_nesting": true },
"MD003": {
"style": "atx"
},
"MD007": {
"indent": 2
},
"MD013": {
"line_length": 120,
"code_blocks": false,
"tables": false
},
Comment on lines +9 to +13
Copy link

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This file change appears to be formatting-only; MD013 already had code_blocks: false and tables: false before. The PR description suggests a behavioral change to exempt code blocks/tables—consider updating the description (or the config, if a different lint behavior was intended) so they align.

Copilot uses AI. Check for mistakes.
"MD024": {
"allow_different_nesting": true
},
"MD033": false,
"MD041": false
}
}
218 changes: 159 additions & 59 deletions mcp/github.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,117 +2,190 @@

## Overview

The GitHub MCP Server is a server that provides a MCP interface for the GitHub API. It is a simple server that can be
used to interact with the GitHub API. Users can use this server to get information about their GitHub repositories,
issues, pull requests, and more.
The GitHub MCP Server provides an MCP interface for the GitHub API. Users can
use this server to interact with GitHub repositories, issues, pull requests, and
more through AI-powered tools like Claude Code and Cursor AI.

> **Note:** The npm package `@modelcontextprotocol/server-github` is
> **deprecated as of April 2025**. Follow the updated instructions below to use
> the official GitHub MCP server (`ghcr.io/github/github-mcp-server` via Docker
> or the remote hosted endpoint).

## GitHub MCP Personal Access Token Setup

To use the GitHub MCP, you need to create a personal access token. GitHub users can create a personal access token
[by navigating to the GitHub settings page](https://github.com/settings/tokens).
To use the GitHub MCP, you need to create a personal access token. GitHub users
can create a personal access token [by navigating to the GitHub settings
page](https://github.com/settings/tokens).

Once on the Personal Access Tokens page, click on 'Generate new token'.

As the first step, provide a descriptive name for your token, such as 'GitHub MCP Token'.
As the first step, provide a descriptive name for your token, such as
'GitHub MCP Token'.

Then, select the required scopes for the token:

- For full access to private repositories, select repo.
- For access to public repositories only, select public_repo.
- For full access to private repositories, select `repo`.
- For access to public repositories only, select `public_repo`.
- Scroll down and click on Generate token.

Copy the generated token and save it securely. This will be used in the various tooling configurations.
Copy the generated token and save it securely. At TLF, we recommend storing this
value into 1Password in your personal vault. This will be used in the various
tooling configurations.

As a last step, users should select the 'Configure SSO' option adjacent to the newly generated token.
From the drop-down, select the 'linuxfoundation' to Authorize the token for use under the Linux
Foundation GitHub organization.
As a last step, users should select the 'Configure SSO' option adjacent to the
newly generated token. From the drop-down, select 'linuxfoundation' to authorize
the token for use under the Linux Foundation GitHub organization.

## Claude Code GitHub MCP Setup

> Note: Before proceeding, ensure that the Personal Access Token has been
> configured for use under the Linux Foundation GitHub organization. See above.

To setup the GitHub MCP for Claude Code (or commonly called Claude CLI), a MCP
configuration entry should be added to the Claude `mcpServers` configuration
section of the `~/.claude.json` file. Once added, Claude Code must be restarted
on the command line. The user must authorize the connection the first time the
MCP connection is used.
Claude Code 2.1.1+ supports connecting directly to the hosted GitHub MCP remote
server over HTTP. This is the recommended approach as it requires no local
Docker installation.

The MCP set up in the `~/.claude.json` file for the LF Atlassian Jira instance
would look like:
### Option 1: Remote Server (Recommended, Claude Code 2.1.1+)

```jsonc
{
//...
"mcpServers": {
"github": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-github"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_PERSONAL_ACCESS_TOKEN"
}
}
}
}
> **Prerequisite:** The remote endpoint (`https://api.githubcopilot.com/mcp`)
> requires an active **GitHub Copilot** subscription (Individual, Business, or
> Enterprise). If your account does not have Copilot access, authentication will
> fail with a 401 or 403 error. Use Option 2 or Option 3 instead.

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 YOUR_GITHUB_PAT"}}'
```

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

> **Security warning:** Do **not** store personal access tokens or secrets in
> `--scope project` configs (`.mcp.json`). Project-scoped files are typically
> committed to version control and will expose your token to everyone with
> repository access. Prefer `--scope user` or `--scope local` for tokens.
> Use environment variables or a secret manager rather than embedding
> `Authorization` headers with real tokens in JSON. If a project-scoped config
> is unavoidable, add `.mcp.json` to `.gitignore` and use a placeholder (e.g.,
> `YOUR_GITHUB_PAT`) in any committed examples.

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"}}'
```

> Note: if you have an existing GitHub MCP installed and configured, you will need
> to disable and remove the old MCP before configuring the new MCP.

### Option 2: Local Docker Deployment

If you prefer to run the server locally, ensure Docker is installed and running.
There are two ways to supply your token:

**Option A — inline value** (replace `YOUR_GITHUB_PAT` with your actual 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
```

**Option B — inherit from shell** (export the variable first, then omit the
value so Docker inherits it from the parent environment):

```bash
export GITHUB_PERSONAL_ACCESS_TOKEN=YOUR_GITHUB_PAT
claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN -- \
docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server
```

Once this is added, users can use the GitHub MCP by restarting Claude Code.
In Option A, `-e GITHUB_PERSONAL_ACCESS_TOKEN=VALUE` passes the token directly
in the `claude mcp` command. In Option B, `-e GITHUB_PERSONAL_ACCESS_TOKEN`
(without `=VALUE`) tells Docker to inherit the variable from your shell
environment, keeping the token out of your shell history and command line.

Comment on lines +108 to +111
Copy link

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Option B still includes the token in the export GITHUB_PERSONAL_ACCESS_TOKEN=... command, which will usually be recorded in shell history. The text claiming it keeps the token out of shell history is misleading; consider rewording to clarify it only avoids putting the token in the claude mcp add/docker run arguments, and suggest a history-safe way to set the env var (e.g., secret manager / prompt input / shell config).

Suggested change
in the `claude mcp` command. In Option B, `-e GITHUB_PERSONAL_ACCESS_TOKEN`
(without `=VALUE`) tells Docker to inherit the variable from your shell
environment, keeping the token out of your shell history and command line.
in the `claude mcp` and `docker` command arguments. In Option B,
`-e GITHUB_PERSONAL_ACCESS_TOKEN` (without `=VALUE`) tells Docker to inherit
the variable from your shell environment, so the token does not appear in
those command arguments. Note that the `export GITHUB_PERSONAL_ACCESS_TOKEN=…`
command itself (and any literal token you type) may still be recorded in your
shell history; consider using a history-safe method to set the variable (for
example, `read -s GITHUB_PERSONAL_ACCESS_TOKEN` in an interactive shell,
a secrets manager integration, or a shell config file that is not committed
to version control).

Copilot uses AI. Check for mistakes.
> **Note:** For Option B, `GITHUB_PERSONAL_ACCESS_TOKEN` must be exported (not
> just set) in your shell so Docker can inherit it as an environment variable.
> A variable set with `VAR=value` (without `export`) is only available to the
> current shell and will not be passed to child processes like Docker.

### Option 3: Binary (No Docker)

Download a release binary from the
[github-mcp-server releases page](https://github.com/github/github-mcp-server/releases),
add it to your `PATH`, then run:

```bash
claude mcp add-json github '{"command":"github-mcp-server","args":["stdio"],"env":{"GITHUB_PERSONAL_ACCESS_TOKEN":"YOUR_GITHUB_PAT"}}'
```

### Claude Code Validation

To validate the setup, start Claude Code and issue the `/mcp` command. This
should return details of the configured MCP servers. The GitHub MCP should
show as being connected.
To validate the setup, run:

```bash
claude mcp list
claude mcp get github
```

You can also start Claude Code and issue the `/mcp` command. The GitHub MCP
should show as connected.

Additionally, you can generate a prompt to inquire about a specific GitHub
pull request, issue, or repository. See [validation section below](#validation)
pull request, issue, or repository. See the [Validation section below](#validation)
for an example.

## Cursor AI GitHub MCP Setup

To configure Cursor AI to use the GitHub MCP, the MCP server needs to be added to
the global MCP configuration.
To configure Cursor AI to use the GitHub MCP, add the MCP server to the global
MCP configuration.

### Cursor Global GitHub MCP Configuration

> Note: Before proceeding, ensure that the Personal Access Token has been
> configured for use under the Linux Foundation GitHub organization. See above.

Here is an example of the Cursor AI MCP configuration for the GitHub MCP:

Edit the `~/.cursor/mcp.json` file to add the GitHub MCP server.
Edit the `~/.cursor/mcp.json` file to add the GitHub MCP server using the
official Docker image:

```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_GITHUB_PAT",
},
Comment on lines +168 to +172
Copy link

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Cursor ~/.cursor/mcp.json example uses trailing commas in the args array and env object. Other MCP config examples in this repo avoid trailing commas (e.g., mcp/jira.md and mcp/playwright.md), and some JSONC parsers are stricter than VS Code’s. Consider removing trailing commas here to keep the example consistent and reduce copy/paste parse errors.

Copilot uses AI. Check for mistakes.
},
},
}
```

### Cursor MCP Setup Validation

Once this is added, users can use the GitHub MCP by viewing the MCP server configuration under
the Cursor AI MCP settings page (View: Open MCP Settings). Under MCP Tools section, the GitHub MCP
should be listed and enabled. There should be a green dot next to the GitHub MCP entry.
Once this is added, users can use the GitHub MCP by viewing the MCP server
configuration under the Cursor AI MCP settings page (View: Open MCP Settings).
Under the MCP Tools section, the GitHub MCP should be listed and enabled with a
green dot next to the entry.

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 to query GitHub
(see [Validation section below](#validation)).
example. Hit `CMD+I` to open the AI assistant within Cursor and enter a prompt
to query GitHub (see [Validation section below](#validation)).

## Validation

Expand All @@ -129,7 +202,34 @@ How many open pull requests are on the lfx-engineering repository?
This should return the number of open pull requests on the lfx-engineering
repository.

## Troubleshooting

**Authentication Issues:**

- Verify the token includes the `repo` scope.
- Confirm the token has not expired.
- Ensure the token is authorized for the `linuxfoundation` GitHub organization
via SSO (Configure SSO → Authorize).

**Remote Server Problems:**

- Validate the endpoint URL: `https://api.githubcopilot.com/mcp`

**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`

**Server Startup Failures:**

- Run `claude mcp list` to review your configuration.
- Check JSON syntax validity.
- Remove and reconfigure: `claude mcp remove github`, then re-add.
- Run the `/mcp` command inside Claude Code to review server status and logs.

## References

1. [How to set up Github MCP server for use with Claude Desktop on Windows and
Mac](https://allthings.how/how-to-set-up-github-mcp-server-for-use-with-claude-desktop-on-windows-and-mac/)
1. [GitHub MCP Server — Official Installation Guide for
Claude](https://github.com/github/github-mcp-server/blob/main/docs/installation-guides/install-claude.md)
2. [GitHub MCP Server Repository](https://github.com/github/github-mcp-server)
Loading