GitHub plugin missing README with authentication setup instructions

[heytcass]

Summary

The GitHub plugin in external_plugins/github/ lacks documentation explaining how to authenticate, leaving users unable to use the plugin without external research.

Current State

The plugin directory structure:

external_plugins/github/
├── .claude-plugin/
│   └── plugin.json
└── .mcp.json

The plugin requires GITHUB_PERSONAL_ACCESS_TOKEN environment variable (per .mcp.json), but:

• No README file exists
• No setup instructions provided
• Users see "not authenticated" with no guidance
• Authentication appears broken when clicking UI's "Authenticate" button (see related issue in claude-code repo)

Expected Documentation

A README.md should include:

1. Authentication Setup

   # Create GitHub Personal Access Token
   # Visit: https://github.com/settings/tokens
   
   # Add to shell profile (~/.zshrc or ~/.bash_profile):
   export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_your_token_here"
   
   # Restart Claude Code or reload terminal

2. Required Token Scopes

   • List minimum required scopes
   • Explain what permissions are needed for different operations

3. Verification Steps

   • How to verify the plugin is working
   • Expected behavior after setup

4. Troubleshooting

   • Common issues (env var not set, wrong scopes, etc.)
   • How to check if token is being read

Impact

• Discoverability: Users can't figure out how to authenticate without:
  • Reading plugin source code
  • External documentation searches
  • Trial and error
• User Experience: Appears broken out-of-box

Plugin Reference

• Location: external_plugins/github/
• .mcp.json configuration:

  {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_PERSONAL_ACCESS_TOKEN}"
      }
    }
  }

Suggested Solution

Add external_plugins/github/README.md following the pattern of other documented plugins in the marketplace. Include clear setup instructions, required environment variables, and troubleshooting guidance.

Related Issues

• Related to claude-code UI issue: MCP UI shows "Authenticate" button for env-var based auth, attempts incompatible OAuth claude-code#21107

[Ashutosh0x]

It seems this is part of a wider issue where multiple plugins (security-guidance, code-simplifier, plugin-dev) are missing either README.md or plugin.json manifests. I've reported similar gaps in #357 and #96.

For GitHub specifically, the setup usually requires:

1. GITHUB_TOKEN environment variable.
2. Or gh auth login flow.

If you confirm the intended auth method (Token vs CLI), I can draft a standard README for this plugin.

[beaugunderson]

hit this today as well and assumed the official plugin was just broken

[jeremiah-snee-openx]

Hit this as well. Seems like anthropic needs to update or add a new client for github oauth

Following oauth from

• feat: update Slack plugin to HTTP transport with OAuth config #406

getting their web based client ID
and updating .mcp.json to

{
  "github": {
    "type": "http",
    "url": "https://api.githubcopilot.com/mcp/",
    "oauth": {
      "clientId": "Iv23liqTIFEtdIu6Vn1r",
      "callbackPort": 3118,
    }
  }
}

returns the following error

---

Also tried to use headersHelper, but that also did not work
https://github.com/anthropics/claude-plugins-official/blob/aa296ec81e8ccb49c9784f167c2c0aa625a86cec/plugins/plugin-dev/skills/mcp-integration/references/authentication.md#dynamic-headers

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headersHelper": "${CLAUDE_PLUGIN_ROOT}/scripts/get-headers.sh"
    }
  }
}

with

#!/usr/bin/env bash
set -euo pipefail

token=""

# 1) Prefer GitHub CLI token if available + user is logged in
if command -v gh >/dev/null 2>&1; then
  token="$(gh auth token 2>/dev/null || true)"
fi

# 2) Fallback to env vars (in order)
if [[ -z "${token}" ]]; then
  token="${GITHUB_TOKEN:-}"
fi

if [[ -z "${token}" ]]; then
  token="${GH_TOKEN:-}"
fi

if [[ -z "${token}" ]]; then
  token="${GITHUB_PERSONAL_ACCESS_TOKEN:-}"
fi

if [[ -z "${token}" ]]; then
  echo "No GitHub token available. Run 'gh auth login' or set GITHUB_TOKEN/GH_TOKEN/GITHUB_PERSONAL_ACCESS_TOKEN." >&2
  exit 1
fi

# Output MUST be JSON object of headers
printf '{ "Authorization": "Bearer %s" }\n' "${token}"

[klappy]

Ran into the same gap. Practical state today for anyone landing here: the plugin reads GITHUB_PERSONAL_ACCESS_TOKEN, and the in-UI “Authenticate” button is unreliable right now — appears to be the same root cause as anthropics/claude-code#3433 (the OAuth flow expects dynamic client registration, which the GitHub endpoint doesn’t support). So a fine-grained PAT with minimal scopes, exported in your shell profile, is the path that actually works until a README lands.

If someone drafts that README (@Ashutosh0x offered above), two things worth including: the minimum scopes per operation, and a note that the PAT is long-lived — scope it tight and rotate it.

Separately, if you’d rather not keep a permanent token in config at all, I’ve been experimenting with short-lived minted tokens as an alternative (https://gitauth.klappy.dev, source-available here on GH klappy/git-repo-auth-mcp) — but for just getting the official plugin working, the scoped PAT above is the answer, it was just too tedious to do by hand for me.