github-mcp-server-js

Built exclusively on the two first-party SDKs from the official providers — no custom HTTP client, no hand-rolled protocol layer:

• 🐙 Octokit.js — GitHub's official REST/GraphQL client. Every tool in this server is a thin, typed wrapper around a verified octokit.rest.* method.

• 🤖 MCP TypeScript — Anthropic's official Model Context Protocol server SDK.

✨ Highlights

• 🧰 Complete surface — 100+ tools across 16 toolsets (issues, pull requests, actions, code security, Copilot admin, ProjectsV2, and more).

• 🔒 Secure by default — flip GITHUB_PERMISSION=read-only and every mutating tool is never even registered.

• 📦 Three install channels — npm (npx), Claude Desktop Extension (.mcpb), or unpacked extension (.zip).

• ✅ Signed releases — every version built by GitHub Actions with npm provenance and Sigstore attestation.

• 🧪 Three-tier test suite — 200+ hermetic unit tests (nock-mocked) plus a 25-assertion read-only integration suite and 2 state-preserving write round-trips against the real GitHub API.

• 🪶 Zero heavy runtime — pure Node 24+, no Docker, no Go, single-file bundle (~2 MB).

Related MCP server: mcp-github-server

💡 Why this project exists

Five gaps in the current GitHub-MCP landscape:

• 🏢 No remote MCP on enterprise GitHub. GHES and most managed enterprise deployments don't yet expose a remote MCP endpoint — run a local server yourself.

• 🗄️ The Anthropic reference server is deprecated. @modelcontextprotocol/server-github is archived. No fixes, no new tools.

• 🐳 The newer official server needs Docker + Go. github/github-mcp-server ships as a Docker-run Go binary — often blocked by enterprise policy.

• 🧰 Broader tool coverage. 100+ tools across 16 toolsets — a superset of the archived server-github and typical gh-CLI wrappers. See Toolsets for the full list.

• 🔒 Read-only mode is one env var. GITHUB_PERMISSION=read-only registers only the 76 read tools; the 30 mutating operations (create_issue, merge_pull_request, star_repo, run_workflow, …) are never exposed to the model. Same binary, one variable, verified by tests.

github-mcp-server-js fills all five — pure Node 24+ / TypeScript, single-file bundle, npx-installable, shipped as both an npm package and a Claude Desktop Extension.

🚀 Quick start

Pick one of three install paths, from easiest to most hands-on.

⚡ Path 1 — npx from Claude Desktop config (recommended for CLI users)

Edit your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add this entry (create the file with { "mcpServers": {} } if it doesn't exist):

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "github-mcp-server-js"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_personal_access_token_here",
        "GITHUB_SERVER_URL": "github.com",
        "GITHUB_PERMISSION": "read-write",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Only GITHUB_TOKEN is required — the other three are shown with their defaults so you can see every knob at a glance. Common adjustments:

• GitHub Enterprise Server: "GITHUB_SERVER_URL": "github.mycompany.com" (bare hostname is fine; the server appends /api/v3 automatically).

• Read-only mode: "GITHUB_PERMISSION": "read-only" — the 30 mutating tools (create_issue, merge_pull_request, star_repo, run_workflow, …) are never registered.

• Verbose logs: "LOG_LEVEL": "debug" prints every request/response summary to stderr; Claude Desktop surfaces stderr in its MCP log. Every line is already JSON — no separate format flag needed.

Restart Claude Desktop. All 100+ tools become available in every new chat.

The server can also run standalone from any terminal:

npx github-mcp-server-js                                # stdio (for MCP clients)
npx github-mcp-server-js --transport=http --port=3000   # standalone HTTP

🖱️ Path 2 — Claude Desktop Extension via drag-drop (.mcpb)

No config-file editing required; the token is stored in the OS keychain.

1. Download github-mcp-server-js-<version>.mcpb from the latest GitHub Release.

2. Open Claude Desktop → Settings → Extensions.

3. Drag the .mcpb file into the Extensions pane.

4. Fill in your GITHUB_TOKEN (masked; stored in the macOS / Windows keychain, never in plaintext). The remaining fields carry sensible defaults.

5. Click Install. All 100+ tools are immediately available.

🛠️ Path 3 — Claude Desktop unpacked extension (.zip, developer mode)

Claude Desktop also supports loading an unpacked extension from a directory. This is useful when you want to inspect the manifest, hot-swap dist/cli.js, or work behind a corporate proxy that blocks .mcpb downloads.

1. Download github-mcp-server-js-<version>.zip from the latest GitHub Release. The archive is byte-identical to the .mcpb; only the extension differs so stock unzip tooling can open it.

2. Extract: unzip github-mcp-server-js-<version>.zip -d github-mcp-server-js.

3. In Claude Desktop → Settings → Extensions, enable developer mode if it isn't already on.

4. Click Install unpacked extension and select the extracted directory.

5. Fill in GITHUB_TOKEN as in Path 2.

Edits to manifest.json or dist/cli.js in the extracted directory take effect on the next Claude Desktop reload — useful for local iteration on a fork.

🏗️ Build the bundles yourself

git clone https://github.com/wuqunfei/github-mcp-server-js
cd github-mcp-server-js
npm ci
npm run pack:mcpb
# → dist/github-mcp-server-js-<version>.mcpb
# → dist/github-mcp-server-js-<version>.zip  (byte-identical copy)

⚙️ Configuration

Configuration is entirely via environment variables. Claude Desktop sets them from the .mcpb user-config form; for npx installs you set them yourself.

🧰 Toolsets

All 16 toolsets are shipped, exposing 100+ tools total. Write tools are only registered when GITHUB_PERMISSION=read-write (the default); read-only mode registers the read tools alone. The Access column indicates: R = registered in read-only mode; W = registered only in read-write mode.

📁 repos — repositories, branches, commits, tags, file contents

🐛 issues — issue CRUD, comments, labels, conversation locking

🔀 pull_requests — PR listing, creation, merging, reviews

🔎 search — repo, code, commit, issue/PR, user search

👤 users — profiles, followers, following, hovercard

📝 gists — list, get, create, update, delete gists

🔔 activity — notifications, starred repos, star/unstar

📦 packages — GitHub Packages owned by the authenticated user

Requires the read:packages token scope. package_type is required and must be one of npm, maven, rubygems, docker, nuget, container.

🔧 misc — utility endpoints

🔌 apps — GitHub App public info and user installations

🪄 copilot — Copilot org-admin (org-owner PAT required)

🏢 orgs_teams — organization inspection and team membership

💻 codespaces — user codespace lifecycle

📋 projects — GitHub ProjectsV2 (org-scoped, read-only)

🛡️ code_security — code scanning, secrets, Dependabot, advisories

Alert-inspection tools require the security_events PAT scope (or public_repo for public repositories).

🎬 actions — workflows, runs, jobs, artifacts, check runs

🧪 Testing

The suite is organized in three tiers, each with a distinct purpose and different guarantees. All three run against the same source; only the network scope and the presence of GITHUB_TOKEN differ.

1. Unit tests — hermetic, mocked

• Location: test/unit/

• Count: 200 +

• Network: none (nock intercepts every HTTP call; test/setup.ts disables outbound connections so an accidental live call fails loudly)

• Runtime: ~1.3 seconds

• When it runs: on every commit via the pre-commit hook and every push via CI

npm test

2. Integration tests — read-only, real API

• Location: test/integration/read-only.test.ts

• Count: 25 assertions across all 16 toolsets against stable public targets (octocat/Hello-World, octokit/octokit.js)

• Network: hits api.github.com — spawns the built dist/cli.js over stdio, exactly as a real MCP client would

• Safety: read-only — no state mutations anywhere

• Skip behavior: if GITHUB_TOKEN is missing, the whole suite is describe.skip'd so CI without a token stays green

GITHUB_TOKEN=ghp_... npm run test:integration

3. Integration tests — read + write, real API, opt-in

• Location: test/integration/write.test.ts (plus everything in tier 2)

• Count: all 25 read-only assertions + 2 write round-trips

• Round-trips (state-preserving):

  1. create_gist → get_gist → update_gist → delete_gist on a scratch gist — asserts the deleted gist 404s after cleanup

  2. star_repo / unstar_repo on a public repo, restoring the prior starred state whichever way it started

• Opt-in gate: requires INTEGRATION_WRITE=1 — the write suite is describe.skip'd otherwise, so it never mutates state by accident

INTEGRATION_WRITE=1 GITHUB_TOKEN=ghp_... npm run test:integration:write

Both integration scripts run npm run build first so the tests exercise the built dist/cli.js over stdio, matching real client usage exactly.

🔐 Build your own bundle (zero trust)

Prefer not to trust binaries we publish? Every release artifact is fully reproducible from source. You audit the code, run the same gates our CI runs, and produce your own .mcpb and .zip — no need to trust the SHA-256 on our GitHub Releases page or the npm registry.

Prerequisites

• Node.js 24+ — verify with node --version

• npm — bundled with Node 24 (currently npm 11.x); no separate install

• git

Full audit + build pipeline

# 1. Clone the repo at the exact release tag you want to reproduce.
git clone https://github.com/wuqunfei/github-mcp-server-js
cd github-mcp-server-js
git checkout v0.1.1

# 2. Audit the code. Nothing is executed yet.
git log --stat v0.1.0..v0.1.1        # review commits between releases
# Or open the tree in your editor and read every changed file.

# 3. Install the exact dependency versions recorded in package-lock.json.
#    No transitive drift, no surprise upgrades.
npm ci

# 4. Run the same gate our release CI runs. Any failure means don't ship.
npm run typecheck
npm run lint
npm run spellcheck
npm audit --audit-level=high
npm test

# 5. Build the self-contained CLI. Every runtime dependency is inlined
#    into a single ~1.85 MB file — nothing loaded from node_modules at runtime.
npm run build                         # → dist/cli.js

# 6. Pack the extension. The pack script:
#      - enforces manifest.json.version === package.json.version
#      - validates manifest.json against the .mcpb v0.1 schema
#      - re-runs the build for freshness
#      - packs and then unpacks the archive to assert exactly the three
#        expected entries (manifest.json, dist/cli.js, assets/icon.png)
npm run pack:mcpb
# → dist/github-mcp-server-js-<version>.mcpb
# → dist/github-mcp-server-js-<version>.zip   (byte-identical copy)

Install your locally built bundle

Drag the resulting .mcpb (or the extracted .zip) into Claude Desktop → Settings → Extensions exactly as in Path 2 or Path 3.

Note on byte reproducibility. The SHA-256 of your local .mcpb may differ from our published artifact because zip entries encode file modification timestamps. The contents are identical when you build from the same commit with the same locked dependencies. To compare content, use npx @anthropic-ai/mcpb unpack <file> <dir> on both archives and diff the extracted trees.

🚢 Releases and provenance

Every published version is built by GitHub Actions from a tagged commit, signed with npm's Trusted Publisher and Sigstore attestation, and shipped as three artifacts:

• 📦 npm package — npm i github-mcp-server-js (installs the bundled dist/cli.js).

• 🧩 .mcpb Claude Desktop Extension — drag-drop install (Path 2).

• 🗜️ .zip alternate archive — byte-identical to the .mcpb; used for the unpacked-extension flow (Path 3) and stock unzip inspection.

🙏 Credits

• Octokit.js by GitHub — the REST/GraphQL client every tool wraps. Apache-2.0.

• MCP TypeScript by Anthropic — the MCP server framework. MIT.

• Prior art: @modelcontextprotocol/server-github (archived, original Anthropic reference server) and github/github-mcp-server (GitHub's official Go / Docker implementation). Both remain excellent choices where their constraints fit.

📄 License

MIT © 2026 Qunfei Wu. See LICENSE.