github-mcp-server-js

<p align="center"> <img src="./assets/icon-248.png" alt="github-mcp-server-js logo — the GitHub Octocat reimagined as a cat-suited kitten" width="200" /> </p> <h2 align="center">Github-MCP-Server-JS</h2> <p align="center"> <strong>🚀 A pure Node.js GitHub MCP server for Claude Desktop and any MCP-compatible client — ⚡ 104 REST tools across 16 toolsets, 🚫 no Docker, 🚫 no Go, 🚫 no Python. ✨</strong> </p> <p align="center"> <a href="https://nodejs.org/"><img src="https://img.shields.io/node/v/github-mcp-server-js.svg" alt="node" /></a> <a href="./LICENSE"><img src="https://img.shields.io/npm/l/github-mcp-server-js.svg" alt="license" /></a> <a href="https://github.com/wuqunfei/github-mcp-server-js/actions/workflows/ci.yml"><img src="https://github.com/wuqunfei/github-mcp-server-js/actions/workflows/ci.yml/badge.svg" alt="CI" /></a> <a href="https://socket.dev/npm/package/github-mcp-server-js"><img src="https://badge.socket.dev/npm/package/github-mcp-server-js" alt="Socket score" /></a> <a href="https://www.npmjs.com/package/github-mcp-server-js"><img src="https://img.shields.io/npm/dw/github-mcp-server-js" alt="NPM Downloads" /></a> <a href="https://github.com/wuqunfei/github-mcp-server-js"><img src="https://img.shields.io/github/stars/wuqunfei/github-mcp-server-js.svg" alt="GitHub stars" /></a> </p>

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).

---

💡 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.

| Variable | Required | Default | Description | |---|---|---|---| | GITHUB_TOKEN | Yes | — | Personal access token used for all GitHub API calls. | | GITHUB_SERVER_URL | No | github.com | GitHub host — bare hostname or full API base URL. Set this for GitHub Enterprise Server. | | GITHUB_PERMISSION | No | read-write | read-only (registers 76 read tools) or read-write (all 100+). | | LOG_LEVEL | No | info | debug, info, or error. Every tool call logs tool_call / tool_ok / tool_error as one JSON object per stderr line, plus an MCP notifications/message for the connected client. |

🧰 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

| Tool | Access | Description | |---|---|---| | get_repository | R | Get a GitHub repository by owner and name. | | list_branches | R | List branches in a repository. | | get_branch | R | Get a single branch in a repository. | | get_file_contents | R | Get the contents of a file or directory in a repository. | | list_commits | R | List commits in a repository. | | get_commit | R | Get a single commit in a repository. | | list_tags | R | List tags in a repository. | | get_tree | R | Get a single tree in a repository, optionally recursive. | | create_or_update_file | W | Create a new file or update an existing file in a repository. | | create_branch | W | Create a new branch from an existing branch or commit SHA. | | delete_branch | W | Delete a branch from a repository. | | create_tree | W | Create a new tree object in a repository. |

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

| Tool | Access | Description | |---|---|---| | list_issues | R | List issues in a repository. | | get_issue | R | Get a single issue in a repository. | | list_comments | R | List comments on an issue. | | list_labels | R | List all labels defined in a repository. | | list_labels_on_issue | R | List the labels currently applied to an issue. | | create_issue | W | Create a new issue in a repository. | | update_issue | W | Update an existing issue. | | add_comment | W | Add a comment to an issue. | | add_labels | W | Add labels to an issue, keeping the issue's existing labels. | | remove_label | W | Remove a single label from an issue. | | lock_issue | W | Lock an issue conversation to collaborators only. | | unlock_issue | W | Unlock a previously locked issue conversation. |

🔀 pull_requests — PR listing, creation, merging, reviews

| Tool | Access | Description | |---|---|---| | list_pull_requests | R | List pull requests in a repository. | | get_pull_request | R | Get a single pull request. | | list_pull_request_files | R | List the files changed in a pull request. | | list_pull_request_commits | R | List the commits on a pull request. | | list_pull_request_reviews | R | List the reviews on a pull request. | | create_pull_request | W | Create a new pull request. | | update_pull_request | W | Update an existing pull request. | | merge_pull_request | W | Merge a pull request. | | create_pull_request_review | W | Create a review on a pull request. | | request_reviewers | W | Request reviewers for a pull request. |

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

| Tool | Access | Description | |---|---|---| | search_repos | R | Search GitHub repositories. q accepts GitHub search qualifiers (e.g. stars:>100 language:go). | | search_code | R | Search code across GitHub. q accepts code-search qualifiers (e.g. repo:foo/bar in:file). | | search_commits | R | Search commits on default branches. q accepts commit-search qualifiers. | | search_issues | R | Search issues and pull requests (scope with is:issue or is:pull-request). | | search_users | R | Search GitHub users. |

👤 users — profiles, followers, following, hovercard

| Tool | Access | Description | |---|---|---| | `get_