diff --git a/README.md b/README.md index 059256aaa..a8e7c7778 100644 --- a/README.md +++ b/README.md @@ -132,9 +132,11 @@ GitHub Enterprise Server does not support remote server hosting. Please refer to 1. To run the server in a container, you will need to have [Docker](https://www.docker.com/) installed. 2. Once Docker is installed, you will also need to ensure Docker is running. The image is public; if you get errors on pull, you may have an expired token and need to `docker logout ghcr.io`. -3. Lastly you will need to [Create a GitHub Personal Access Token](https://github.com/settings/personal-access-tokens/new). +3. Lastly you will need to [Create a GitHub Personal Access Token](https://github.com/settings/personal-access-tokens/new) or use an OAuth token from your IDE/toolchain. The MCP server can use many of the GitHub APIs, so enable the permissions that you feel comfortable granting your AI tools (to learn more about access tokens, please check out the [documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)). +> **Note**: The server accepts any valid GitHub access token (PAT or OAuth). The `GITHUB_ACCESS_TOKEN` environment variable is preferred over the deprecated `GITHUB_PERSONAL_ACCESS_TOKEN` variable. +
Handling PATs Securely ### Environment Variables (Recommended) @@ -158,11 +160,11 @@ To keep your GitHub PAT secure and reusable across different MCP hosts: 3. **Reference the token in configurations** ```bash # CLI usage - claude mcp update github -e GITHUB_PERSONAL_ACCESS_TOKEN=$GITHUB_PAT + claude mcp update github -e GITHUB_ACCESS_TOKEN=$GITHUB_PAT # In config files (where supported) "env": { - "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_PAT" + "GITHUB_ACCESS_TOKEN": "$GITHUB_PAT" } ``` @@ -199,13 +201,13 @@ the hostname for GitHub Enterprise Server or GitHub Enterprise Cloud with data r "-i", "--rm", "-e", - "GITHUB_PERSONAL_ACCESS_TOKEN", + "GITHUB_ACCESS_TOKEN", "-e", "GITHUB_HOST", "ghcr.io/github/github-mcp-server" ], "env": { - "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}", + "GITHUB_ACCESS_TOKEN": "${input:github_token}", "GITHUB_HOST": "https://" } } @@ -242,11 +244,11 @@ Add the following JSON block to your IDE's MCP settings. "-i", "--rm", "-e", - "GITHUB_PERSONAL_ACCESS_TOKEN", + "GITHUB_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server" ], "env": { - "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}" + "GITHUB_ACCESS_TOKEN": "${input:github_token}" } } } @@ -278,11 +280,11 @@ Optionally, you can add a similar example (i.e. without the mcp key) to a file c "-i", "--rm", "-e", - "GITHUB_PERSONAL_ACCESS_TOKEN", + "GITHUB_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server" ], "env": { - "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}" + "GITHUB_ACCESS_TOKEN": "${input:github_token}" } } } @@ -308,7 +310,7 @@ For a complete overview of all installation options, see our **[Installation Gui ### Build from source If you don't have Docker, you can use `go build` to build the binary in the -`cmd/github-mcp-server` directory, and use the `github-mcp-server stdio` command with the `GITHUB_PERSONAL_ACCESS_TOKEN` environment variable set to your token. To specify the output location of the build, use the `-o` flag. You should configure your server to use the built executable as its `command`. For example: +`cmd/github-mcp-server` directory, and use the `github-mcp-server stdio` command with the `GITHUB_ACCESS_TOKEN` environment variable set to your token. To specify the output location of the build, use the `-o` flag. You should configure your server to use the built executable as its `command`. For example: ```JSON { @@ -318,7 +320,7 @@ If you don't have Docker, you can use `go build` to build the binary in the "command": "/path/to/github-mcp-server", "args": ["stdio"], "env": { - "GITHUB_PERSONAL_ACCESS_TOKEN": "" + "GITHUB_ACCESS_TOKEN": "" } } } @@ -392,7 +394,7 @@ When using Docker, you can pass the toolsets as environment variables: ```bash docker run -i --rm \ - -e GITHUB_PERSONAL_ACCESS_TOKEN= \ + -e GITHUB_ACCESS_TOKEN= \ -e GITHUB_TOOLSETS="repos,issues,pull_requests,actions,code_security" \ ghcr.io/github/github-mcp-server ``` @@ -404,13 +406,13 @@ When using Docker, you can pass specific tools as environment variables. You can ```bash # Tools only docker run -i --rm \ - -e GITHUB_PERSONAL_ACCESS_TOKEN= \ + -e GITHUB_ACCESS_TOKEN= \ -e GITHUB_TOOLS="get_file_contents,issue_read,create_pull_request" \ ghcr.io/github/github-mcp-server # Tools combined with toolsets (additive) docker run -i --rm \ - -e GITHUB_PERSONAL_ACCESS_TOKEN= \ + -e GITHUB_ACCESS_TOKEN= \ -e GITHUB_TOOLSETS="repos,issues" \ -e GITHUB_TOOLS="get_gist" \ ghcr.io/github/github-mcp-server @@ -1344,7 +1346,7 @@ When using Docker, you can pass the toolsets as environment variables: ```bash docker run -i --rm \ - -e GITHUB_PERSONAL_ACCESS_TOKEN= \ + -e GITHUB_ACCESS_TOKEN= \ -e GITHUB_DYNAMIC_TOOLSETS=1 \ ghcr.io/github/github-mcp-server ``` @@ -1361,7 +1363,7 @@ When using Docker, you can pass the read-only mode as an environment variable: ```bash docker run -i --rm \ - -e GITHUB_PERSONAL_ACCESS_TOKEN= \ + -e GITHUB_ACCESS_TOKEN= \ -e GITHUB_READ_ONLY=1 \ ghcr.io/github/github-mcp-server ``` @@ -1378,7 +1380,7 @@ When running with Docker, set the corresponding environment variable: ```bash docker run -i --rm \ - -e GITHUB_PERSONAL_ACCESS_TOKEN= \ + -e GITHUB_ACCESS_TOKEN= \ -e GITHUB_LOCKDOWN_MODE=1 \ ghcr.io/github/github-mcp-server ``` diff --git a/cmd/github-mcp-server/main.go b/cmd/github-mcp-server/main.go index cfb68be4e..21ac90275 100644 --- a/cmd/github-mcp-server/main.go +++ b/cmd/github-mcp-server/main.go @@ -32,9 +32,14 @@ var ( Short: "Start stdio server", Long: `Start a server that communicates via standard input/output streams using JSON-RPC messages.`, RunE: func(_ *cobra.Command, _ []string) error { - token := viper.GetString("personal_access_token") + // Check for GITHUB_ACCESS_TOKEN first (preferred), then fall back to + // GITHUB_PERSONAL_ACCESS_TOKEN (deprecated but still supported) + token := viper.GetString("access_token") if token == "" { - return errors.New("GITHUB_PERSONAL_ACCESS_TOKEN not set") + token = viper.GetString("personal_access_token") + } + if token == "" { + return errors.New("GITHUB_ACCESS_TOKEN or GITHUB_PERSONAL_ACCESS_TOKEN not set") } // If you're wondering why we're not using viper.GetStringSlice("toolsets"), diff --git a/docs/installation-guides/install-antigravity.md b/docs/installation-guides/install-antigravity.md index c24d8e01d..5dfb978ad 100644 --- a/docs/installation-guides/install-antigravity.md +++ b/docs/installation-guides/install-antigravity.md @@ -85,11 +85,11 @@ If you prefer running the server locally with Docker: "-i", "--rm", "-e", - "GITHUB_PERSONAL_ACCESS_TOKEN", + "GITHUB_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server" ], "env": { - "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT" + "GITHUB_ACCESS_TOKEN": "YOUR_GITHUB_PAT" } } } diff --git a/docs/installation-guides/install-claude.md b/docs/installation-guides/install-claude.md index 1a5b789f4..ece7b5f37 100644 --- a/docs/installation-guides/install-claude.md +++ b/docs/installation-guides/install-claude.md @@ -45,12 +45,12 @@ claude mcp add --transport http github https://api.githubcopilot.com/mcp -H "Aut ### With Docker 1. Run the following command in the Claude Code CLI: ```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 +claude mcp add github -e GITHUB_ACCESS_TOKEN=YOUR_GITHUB_PAT -- docker run -i --rm -e GITHUB_ACCESS_TOKEN ghcr.io/github/github-mcp-server ``` With an environment variable: ```bash -claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=$(grep GITHUB_PAT .env | cut -d '=' -f2) -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server +claude mcp add github -e GITHUB_ACCESS_TOKEN=$(grep GITHUB_PAT .env | cut -d '=' -f2) -- docker run -i --rm -e GITHUB_ACCESS_TOKEN ghcr.io/github/github-mcp-server ``` 2. Restart Claude Code 3. Run `claude mcp list` to see if the GitHub server is configured @@ -61,7 +61,7 @@ claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=$(grep GITHUB_PAT .env | c 2. Add to your `PATH` 3. Run: ```bash -claude mcp add-json github '{"command": "github-mcp-server", "args": ["stdio"], "env": {"GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT"}}' +claude mcp add-json github '{"command": "github-mcp-server", "args": ["stdio"], "env": {"GITHUB_ACCESS_TOKEN": "YOUR_GITHUB_PAT"}}' ``` 2. Restart Claude Code 3. Run `claude mcp list` to see if the GitHub server is configured @@ -104,11 +104,11 @@ Add this codeblock to your `claude_desktop_config.json`: "-i", "--rm", "-e", - "GITHUB_PERSONAL_ACCESS_TOKEN", + "GITHUB_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server" ], "env": { - "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT" + "GITHUB_ACCESS_TOKEN": "YOUR_GITHUB_PAT" } } } diff --git a/docs/installation-guides/install-cursor.md b/docs/installation-guides/install-cursor.md index 654f0a788..bf7f1d28b 100644 --- a/docs/installation-guides/install-cursor.md +++ b/docs/installation-guides/install-cursor.md @@ -61,11 +61,11 @@ The local GitHub MCP server runs via Docker and requires Docker Desktop to be in "-i", "--rm", "-e", - "GITHUB_PERSONAL_ACCESS_TOKEN", + "GITHUB_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server" ], "env": { - "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT" + "GITHUB_ACCESS_TOKEN": "YOUR_GITHUB_PAT" } } } diff --git a/docs/installation-guides/install-gemini-cli.md b/docs/installation-guides/install-gemini-cli.md index 20764384c..a7cf99a72 100644 --- a/docs/installation-guides/install-gemini-cli.md +++ b/docs/installation-guides/install-gemini-cli.md @@ -72,11 +72,11 @@ With docker running, you can run the GitHub MCP server in a container: "-i", "--rm", "-e", - "GITHUB_PERSONAL_ACCESS_TOKEN", + "GITHUB_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server" ], "env": { - "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_MCP_PAT" + "GITHUB_ACCESS_TOKEN": "$GITHUB_MCP_PAT" } } } @@ -97,7 +97,7 @@ Then, replacing `/path/to/binary` with the actual path to your binary, configure "command": "/path/to/binary", "args": ["stdio"], "env": { - "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_MCP_PAT" + "GITHUB_ACCESS_TOKEN": "$GITHUB_MCP_PAT" } } } diff --git a/docs/installation-guides/install-other-copilot-ides.md b/docs/installation-guides/install-other-copilot-ides.md index a3200179c..798388498 100644 --- a/docs/installation-guides/install-other-copilot-ides.md +++ b/docs/installation-guides/install-other-copilot-ides.md @@ -56,11 +56,11 @@ For users who prefer to run the GitHub MCP server locally. Requires Docker insta "type": "stdio", "command": "docker", "args": [ - "run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", + "run", "-i", "--rm", "-e", "GITHUB_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server" ], "env": { - "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_pat}" + "GITHUB_ACCESS_TOKEN": "${input:github_pat}" } } } @@ -116,11 +116,11 @@ For users who prefer to run the GitHub MCP server locally. Requires Docker insta "command": "docker", "args": [ "run", "-i", "--rm", - "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", + "-e", "GITHUB_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server" ], "env": { - "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT" + "GITHUB_ACCESS_TOKEN": "YOUR_GITHUB_PAT" } } } @@ -172,11 +172,11 @@ For users who prefer to run the GitHub MCP server locally. Requires Docker insta "command": "docker", "args": [ "run", "-i", "--rm", - "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", + "-e", "GITHUB_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server" ], "env": { - "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT" + "GITHUB_ACCESS_TOKEN": "YOUR_GITHUB_PAT" } } } @@ -229,11 +229,11 @@ For users who prefer to run the GitHub MCP server locally. Requires Docker insta "command": "docker", "args": [ "run", "-i", "--rm", - "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", + "-e", "GITHUB_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server" ], "env": { - "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT" + "GITHUB_ACCESS_TOKEN": "YOUR_GITHUB_PAT" } } } diff --git a/docs/installation-guides/install-windsurf.md b/docs/installation-guides/install-windsurf.md index 8793e2edb..fd8257b42 100644 --- a/docs/installation-guides/install-windsurf.md +++ b/docs/installation-guides/install-windsurf.md @@ -40,11 +40,11 @@ Windsurf supports Streamable HTTP servers with a `serverUrl` field: "-i", "--rm", "-e", - "GITHUB_PERSONAL_ACCESS_TOKEN", + "GITHUB_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server" ], "env": { - "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT" + "GITHUB_ACCESS_TOKEN": "YOUR_GITHUB_PAT" } } } diff --git a/docs/server-configuration.md b/docs/server-configuration.md index e8b7637bd..1d4012015 100644 --- a/docs/server-configuration.md +++ b/docs/server-configuration.md @@ -64,7 +64,7 @@ The examples below use VS Code configuration format to illustrate the concepts. "--tools=get_file_contents,get_me,pull_request_read" ], "env": { - "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}" + "GITHUB_ACCESS_TOKEN": "${input:github_token}" } } ``` @@ -108,7 +108,7 @@ The examples below use VS Code configuration format to illustrate the concepts. "--toolsets=issues,pull_requests" ], "env": { - "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}" + "GITHUB_ACCESS_TOKEN": "${input:github_token}" } } ``` @@ -156,7 +156,7 @@ Enable entire toolsets, then add individual tools from toolsets you don't want f "--tools=get_gist,pull_request_read" ], "env": { - "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}" + "GITHUB_ACCESS_TOKEN": "${input:github_token}" } } ``` @@ -217,7 +217,7 @@ When active, this mode will disable all tools that are not read-only even if the "--read-only" ], "env": { - "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}" + "GITHUB_ACCESS_TOKEN": "${input:github_token}" } } ``` @@ -252,7 +252,7 @@ Starts with only discovery tools (`enable_toolset`, `list_available_toolsets`, ` "--dynamic-toolsets" ], "env": { - "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}" + "GITHUB_ACCESS_TOKEN": "${input:github_token}" } } ``` @@ -270,7 +270,7 @@ Starts with only discovery tools (`enable_toolset`, `list_available_toolsets`, ` "--tools=get_me,search_code" ], "env": { - "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}" + "GITHUB_ACCESS_TOKEN": "${input:github_token}" } } ``` @@ -319,7 +319,7 @@ Lockdown mode ensures the server only surfaces content in public repositories fr "--lockdown-mode" ], "env": { - "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}" + "GITHUB_ACCESS_TOKEN": "${input:github_token}" } } ``` diff --git a/e2e.test b/e2e.test deleted file mode 100755 index 58505b3a2..000000000 Binary files a/e2e.test and /dev/null differ diff --git a/e2e/README.md b/e2e/README.md index 62730431a..615a7f8e4 100644 --- a/e2e/README.md +++ b/e2e/README.md @@ -16,7 +16,7 @@ Since these tests require a token to interact with real resources on the GitHub GITHUB_MCP_SERVER_E2E_TOKEN= go test -v --tags e2e ./e2e ``` -The `GITHUB_MCP_SERVER_E2E_TOKEN` environment variable is mapped to `GITHUB_PERSONAL_ACCESS_TOKEN` internally, but separated to avoid accidental reuse of credentials. +The `GITHUB_MCP_SERVER_E2E_TOKEN` environment variable is mapped to `GITHUB_ACCESS_TOKEN` internally, but separated to avoid accidental reuse of credentials. ## Example diff --git a/e2e/e2e_test.go b/e2e/e2e_test.go index 86ff45b29..f47cc8356 100644 --- a/e2e/e2e_test.go +++ b/e2e/e2e_test.go @@ -174,7 +174,7 @@ func setupMCPClient(t *testing.T, options ...clientOption) *mcp.ClientSession { "-i", "--rm", "-e", - "GITHUB_PERSONAL_ACCESS_TOKEN", // Personal access token is all required + "GITHUB_ACCESS_TOKEN", // GitHub access token (PAT or OAuth) } host := getE2EHost() @@ -193,7 +193,7 @@ func setupMCPClient(t *testing.T, options ...clientOption) *mcp.ClientSession { // Construct the env vars for the MCP Client to execute docker with // We need to include os.Environ() so docker can find its socket and config dockerEnvVars := append(os.Environ(), - fmt.Sprintf("GITHUB_PERSONAL_ACCESS_TOKEN=%s", token), + fmt.Sprintf("GITHUB_ACCESS_TOKEN=%s", token), fmt.Sprintf("GITHUB_TOOLSETS=%s", strings.Join(opts.enabledToolsets, ",")), ) diff --git a/script/conformance-test b/script/conformance-test index 3ff0a55c2..78599f6e2 100755 --- a/script/conformance-test +++ b/script/conformance-test @@ -124,7 +124,7 @@ run_mcp_test() { echo "$LIST_RESOURCES_MSG" echo "$LIST_PROMPTS_MSG" sleep 0.5 - ) | GITHUB_PERSONAL_ACCESS_TOKEN=1 $binary stdio $flags 2>/dev/null + ) | GITHUB_ACCESS_TOKEN=1 $binary stdio $flags 2>/dev/null ) end_time=$(date +%s.%N) @@ -182,7 +182,7 @@ run_mcp_dynamic_test() { sleep 0.1 echo "$LIST_TOOLSETS_AFTER_MSG" sleep 0.3 - ) | GITHUB_PERSONAL_ACCESS_TOKEN=1 $binary stdio $flags 2>/dev/null + ) | GITHUB_ACCESS_TOKEN=1 $binary stdio $flags 2>/dev/null ) end_time=$(date +%s.%N)