{ "markdown": "# github-mcp\n\n\n\n\n

\n \"License\"\n \"GitHub\n \"Last\n \"Open\n \"PyPI\n \"PyPI\n \"Built\n

\n\n\n\nSelf-hosted GitHub MCP server. Personal-access-token auth, stdio transport, transport-agnostic so it works with Claude Code (any account), Codex CLI, Cursor, or any MCP-compliant client. No claude.ai OAuth dependency.\n\nWritten in Python on top of FastMCP. Slots into the same install pattern as other community Python MCP servers.\n\n## Why this exists\n\nThe official `github/github-mcp-server` (Go, 60+ tools) is excellent if you want a kitchen-sink server tied to a single agent platform's auth flow. This one is scoped for operators who:\n\n- Switch between multiple Claude accounts, Codex CLI, Cursor, or other MCP clients and want the same GitHub auth across all of them.\n- Prefer a small, audited tool surface scoped to PR + repo file + Dependabot operations.\n- Want a Python install that lives alongside their other MCP servers.\n\nIf neither applies, run `github/github-mcp-server` instead — that's the right call.\n\n## Tool surface (v0.1.0)\n\n| Tool | Purpose |\n|---|---|\n| `health_check` | Verify the PAT is valid + report rate-limit headroom. First call when wiring up. |\n| `list_prs` | List pull requests with state filter. |\n| `get_pr` | Single PR with check-run status + mergeable state. |\n| `merge_pr` | Squash/merge/rebase with optional branch delete. |\n| `list_dependabot_alerts` | Alert sweep with severity-grouped counts. |\n| `get_file` | Read a file via the Contents API. |\n| `put_file` | Create or update a file via the Contents API (idempotent with SHA). |\n\nFuture versions expand: workflows, releases, issues, rulesets, secret-scan alerts, branch protection, repo settings.\n\n## Secret hygiene (read this first)\n\n**v0.1.1+ reads the PAT from macOS Keychain by default.** Env-var fallback is still supported for non-macOS / CI, but the Keychain path is the recommended setup because the secret never enters argv or process env — safe from `ps aux`, `pgrep -fl`, `lsof`, `/proc//environ`, panic dumps, CI logs, debuggers, or any LLM agent running an introspection command.\n\n```bash\n# One-time setup (macOS):\nsecurity add-generic-password -s github-mcp -a \"$USER\" -w \"\"\n\n# Update later (e.g. after rotation):\nsecurity delete-generic-password -s github-mcp -a \"$USER\" 2>/dev/null\nsecurity add-generic-password -s github-mcp -a \"$USER\" -w \"\"\n```\n\n**Do NOT** install with an inline `--env`:\n\n```bash\n# BAD — bakes the PAT into ~/.claude.json + every Claude child spawn's --mcp-config argv.\n# Any pgrep / ps aux dumps it.\nclaude mcp add github --scope user --env GITHUB_TOKEN=github_pat_... -- \n\n# GOOD — no --env block. The server reads from Keychain at call time.\nclaude mcp add github --scope user -- \n```\n\nPR/incident lineage: this hygiene path was added 2026-05-19 after a `pgrep -fl chrome-devtools-mcp` dumped a PAT-bearing claude process into a session transcript. See [adelaidasofia/github-mcp Keychain migration]() (TODO: link PR once merged).\n\nFor non-macOS environments, fall back to env:\n\n```bash\nexport GITHUB_TOKEN= # set in shell rc, NOT in argv\n```\n\nMinimum scopes for the v0.1 tool surface: Contents R/W, Pull requests R/W, Dependabot R.\n\n## Install\n\nOpen Claude Code, paste:\n\n /plugin marketplace add adelaidasofia/github-mcp\n /plugin install github-mcp@github-mcp\n\n
Legacy install\n\n```bash\ngit clone https://github.com/adelaidasofia/github-mcp ~/.claude/github-mcp\ncd ~/.claude/github-mcp\nuv tool install --editable .\n```\n\nOr as a one-off without persistent install:\n\n```bash\ncd ~/.claude/github-mcp\nuv run github-mcp\n```\n\n
\n\n## Auth\n\nThe server reads the GitHub PAT from environment, in this precedence:\n\n1. `GITHUB_TOKEN`\n2. `GH_TOKEN`\n\nFine-grained tokens recommended.\n\n### Scope matrix\n\n| Permission | Access | Unlocks |\n|---|---|---|\n| Metadata | Read | Baseline (auto-required when any other repo permission is set) |\n| Contents | Read and write | `get_file`, `put_file` |\n| Pull requests | Read and write | `list_prs`, `get_pr`, `merge_pr` |\n| Dependabot alerts | Read | `list_dependabot_alerts` |\n| Administration | Read and write | Future: rulesets, branch protection, `allow_auto_merge` toggle |\n| Workflows | Read and write | Future: read/update `.github/workflows/*.yml` |\n| Actions | Read and write | Future: trigger and inspect workflow runs |\n| Secret scanning alerts | Read | Future: fleet-wide secret-scan sweep |\n| Code scanning alerts | Read | Future: CodeQL fleet sweep |\n\n**v0.1 floor**: Metadata + Contents (R/W) + Pull requests (R/W) + Dependabot alerts (R) is enough to use every tool in this release.\n\n**Future-proof**: granting the full table now means new MCP tools can ship without rotating the PAT. Equivalent to checking \"all repository permissions\" in the fine-grained PAT UI. Trade-off: broader blast radius if the token leaks. Reasonable for a personal-dev token on an encrypted laptop with FileVault; reconsider for shared or production deployments.\n\nThe MCP introspects scopes via `health_check` — call it after wiring up to confirm what your token actually has.\n\nOptional: `GITHUB_API_BASE` for GitHub Enterprise Server. Defaults to `https://api.github.com`.\n\n## Wire into an MCP client\n\n### Claude Code\n\nAdd to `~/.claude/.mcp.json` (or any `.mcp.json` in the project root):\n\n```json\n{\n \"mcpServers\": {\n \"github\": {\n \"command\": \"uv\",\n \"args\": [\"run\", \"--project\", \"/Users//.claude/github-mcp\", \"github-mcp\"],\n \"env\": {\n \"GITHUB_TOKEN\": \"${GITHUB_TOKEN}\"\n }\n }\n }\n}\n```\n\n### Codex CLI\n\nAdd to `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.github]\ncommand = \"uv\"\nargs = [\"run\", \"--project\", \"/Users//.claude/github-mcp\", \"github-mcp\"]\n\n[mcp_servers.github.env]\nGITHUB_TOKEN = \"${GITHUB_TOKEN}\"\n```\n\n### Cursor\n\n`~/.cursor/mcp.json` follows the Claude Code shape. Same env block.\n\n### Any other MCP-compliant client\n\nConfigure it to spawn the `github-mcp` command and pipe stdio. The server speaks standard MCP over stdio.\n\n## Verify\n\n```bash\nGITHUB_TOKEN=ghp_yourpat uv run github-mcp\n```\n\nThe server will wait on stdin for MCP traffic. In another shell, exercise `health_check` via your client.\n\n## Test\n\n```bash\nuv pip install -e \".[dev]\"\nuv run pytest tests/ -v\n```\n\n\n## Telemetry\n\nThis plugin sends a single anonymous install signal to `myceliumai.co` the first time it loads in a Claude Code session on a given machine.\n\n**What is sent:**\n- Plugin name (e.g. `slack-mcp`)\n- Plugin version (e.g. `0.1.0`)\n\n**What is NOT sent:**\n- No user identifiers, names, emails, tokens, or API keys\n- No file paths, message content, or anything from your work\n- No IP address is stored after dedup processing\n\n**Why:** Helps the maintainer know which plugins people actually install, so attention goes to the ones that get used.\n\n**Opt out:** Set the environment variable `MYCELIUM_NO_PING=1` before launching Claude Code. The hook will skip the network call entirely. Already-pinged installs leave a sentinel at `~/.mycelium/onboarded-` — delete it if you want to reset state.\n\n## License\n\nMIT.\n", "bytes": 8272, "sha": "df292cee6f2f7d69625cf8271a6bd3d7aa36f33e2401ffb7b02b3f910f9ac428", "repo_slug": "adelaidasofia/github-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/plg_adelaidasofia_github_mcp_github_mcp_b8093403/readme" }