GitHub MCP Server (Kosta's Version)

A Model Context Protocol (MCP) server providing comprehensive GitHub repository operations — read and write — through a simple CLI interface. Built for Claude Desktop and other MCP clients.

v3.1.0 — Combines v3 write-tool expansion with Streamable HTTP transport (/mcp), OAuth cutover scaffolding, lazy tool loading, and structured tool output options.

Features

Repository exploration, file reading, and code search
Full issue/PR lifecycle (list, view, create, update, merge, reviewers, labels)
Commit history, diffs, and branch comparison
File creation/updates/deletion via direct commits
Branch creation and deletion
Release, repository create/fork, and user info
Tool annotations (readOnly, destructive hints) for smart AI tool selection
Server instructions for AI workflow guidance
Rate limiting and comprehensive error handling

Installation & Usage

Quick Start (Recommended)

# Run directly with npx (no installation needed)
GITHUB_TOKEN=your_token_here npx github-mcp-server-kosta

# Idle auto-exit defaults to 5 minutes (prevents leaked stdio servers from piling up).
# Disable if you need an always-on process:
MCP_IDLE_TIMEOUT_MS=0 GITHUB_TOKEN=your_token_here npx github-mcp-server-kosta

# Not recommended (token is visible via `ps` on the machine):
npx github-mcp-server-kosta --github-token YOUR_GITHUB_TOKEN

# Streamable HTTP mode (native /mcp endpoint)
GITHUB_TOKEN=your_token_here npx github-mcp-server-kosta --transport http --http-port 3000

Global Installation

npm install -g github-mcp-server-kosta
GITHUB_TOKEN=your_token_here github-mcp-server-kosta

GitHub Token Setup

Go to GitHub Settings → Developer settings → Personal access tokens
Generate a new token (classic) with these scopes:
- repo (full access for private repos + write operations)
- public_repo (for public repositories, read-only)
- read:user (for user information)
Use the token with the CLI:

npx github-mcp-server-kosta --github-token ghp_your_token_here

Available Tools

Repository Operations

Tool	Description
`github_repo_info`	Get repository metadata (stars, forks, language, etc.)
`github_list_contents`	List files/directories at a path
`github_get_file_content`	Read a file's content (returns SHA for updates)
`github_get_readme`	Fetch and decode the README
`github_search_code`	Search code within a repository
`github_list_repos`	List repositories for a user/organization
`github_search_repos`	Search repositories globally
`github_create_repo`	Create a new repository
`github_fork_repo`	Fork an existing repository

Issues & Pull Requests

Tool	Description
`github_list_issues`	List issues (filter by state, labels, assignee)
`github_get_issue`	Get full issue details
`github_list_pulls`	List PRs (filter by state, head, base branch)
`github_get_pull`	Get full PR details with diff stats
`github_create_issue`	Create a new issue
`github_update_issue`	Update an issue (or PR) via Issues API (title/body/state/labels/assignees/milestone)
`github_create_issue_comment`	Comment on an issue or PR
`github_create_pull_request`	Create a pull request
`github_update_pull_request`	Update a pull request
`github_merge_pull_request`	Merge a pull request
`github_request_reviewers`	Request reviewers for a pull request
`github_search_issues`	Search issues and pull requests (GitHub search syntax)

Branches, Commits & History

Tool	Description
`github_list_branches`	List all branches
`github_list_commits`	List commits (filter by path, author, date)
`github_get_commit`	Get commit details with full diff
`github_compare`	Compare two branches/tags/commits
`github_create_branch`	Create a new branch from a ref
`github_delete_branch`	Delete a branch

Releases & Users

Tool	Description
`github_list_releases`	List releases with notes and assets
`github_create_release`	Create a release
`github_user_info`	Get user/org profile info

File Operations

Tool	Description
`github_create_or_update_file`	Create or update a file via commit
`github_delete_file`	Delete a file via commit (requires SHA)

Labels

Tool	Description
`github_list_labels`	List repository labels
`github_create_label`	Create a repository label
`github_set_issue_labels`	Replace all labels on an issue/PR
`github_add_issue_labels`	Add labels to an issue/PR
`github_remove_issue_label`	Remove a label from an issue/PR
`github_add_labels`	Compatibility alias: add labels to issue/PR
`github_remove_label`	Compatibility alias: remove a single label

Lazy Tool Loading (Optional)

Tool	Description
`github_tool_groups_list`	List tool groups and whether they are loaded
`github_tool_groups_load`	Load tool groups and emit `notifications/tools/list_changed`
`github_tool_catalog_search`	Search groups/tool names without loading all tools

REST Escape Hatch

Tool	Description
`github_rest_get`	Generic GET against GitHub REST API (path-based)
`github_rest_mutate`	Generic write request (POST/PUT/PATCH/DELETE) guarded by `confirm: "CONFIRM_GITHUB_WRITE"`

MCP Client Configuration

For Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["github-mcp-server-kosta", "--github-token", "YOUR_GITHUB_TOKEN"]
    }
  }
}

CLI Options

Options:
  -t, --github-token     GitHub access token for API requests (or set GITHUB_TOKEN / GITHUB_PERSONAL_ACCESS_TOKEN)
      --transport        Transport mode: stdio|http [default: stdio]
      --tool-mode        Tool listing mode: "full" or "lazy" [default: full]
      --preload-groups   Comma-separated tool group IDs to preload in lazy mode [default: core,search in lazy]
      --tool-schema-verbosity  Tool schema verbosity: "full" or "compact" [default: full]
      --tool-output      Tool output: text|structured|both [default: text]
      --tool-output-schema  Tool output schema: none|bootstrap|all_loose [default: none]
      --idle-timeout-ms  Exit after this many ms without receiving an MCP request (0 disables).
                         Defaults: stdio=0, http=300000 (unless MCP_IDLE_TIMEOUT_MS is set)
  -r, --rate-limit       Rate limit delay in ms between requests [default: 100]
      --http-host        HTTP bind host (http transport) [default: 127.0.0.1]
      --http-port        HTTP bind port (http transport; 0 chooses ephemeral) [default: 3000]
      --http-path        MCP endpoint path (http transport) [default: /mcp]
      --http-tls-key     TLS private key path (enables https when paired with --http-tls-cert)
      --http-tls-cert    TLS cert path (enables https when paired with --http-tls-key)
      --http-auth-token  Optional Bearer token required to access /mcp
      --http-allowed-origins  Comma-separated Origin allowlist (enforced only when Origin header is present)
      --http-allowed-hosts    Comma-separated Host allowlist (recommended when binding 0.0.0.0/::)
      --http-max-sessions     Maximum concurrent MCP sessions (DoS guard) [default: 50]
      --http-require-auth-on-public-bind  Refuse startup if binding non-localhost without --http-auth-token [default: false]
      --http-oauth-resource-metadata-url  Optional URL to advertise in WWW-Authenticate as resource_metadata
      --http-oauth-protected-resource-path  Optional local path to serve OAuth protected resource metadata JSON
      --http-oauth-authorization-server-issuer  Optional authorization server issuer included in metadata
      --http-oauth-scopes  Comma-separated scopes_supported included in metadata
      --http-oauth-cutover-path  Optional second MCP endpoint path for staged OAuth cutover (example: /mcp-oauth)
      --http-oauth-cutover-token  Bearer token required on cutover endpoint (falls back to --http-auth-token)
  -h, --help             Show help

Lazy Tool Loading Notes

In --tool-mode lazy, the server only exposes bootstrap tools plus any preloaded groups (default: core,search).
Load additional groups at runtime using github_tool_groups_load (e.g., issues, pulls, rest).
The server advertises tools.listChanged: true and emits notifications/tools/list_changed after loading groups, but some MCP clients may not auto-refresh tool lists. If your client does not, call tools/list again (or restart the session).

Streamable HTTP (`/mcp`) Notes

--transport http exposes a single MCP endpoint (default http://127.0.0.1:3000/mcp) supporting GET, POST, and DELETE.
By default the server binds to 127.0.0.1 for safety. If you bind to 0.0.0.0 or another interface, you should set --http-auth-token and strongly consider --http-allowed-hosts and --http-allowed-origins.
In HTTP mode, lazy tool loading state is session-isolated: each Mcp-Session-Id gets its own tool-group load state.
Optional stricter startup guard: --http-require-auth-on-public-bind true refuses startup when binding non-localhost without --http-auth-token.

supergateway + Cloudflare Baseline

If you run this behind supergateway for Claude.ai remote connectors, pin the gateway transport/session/protocol flags explicitly:

supergateway \
  --stdio 'npx github-mcp-server-kosta -t "$GITHUB_TOKEN"' \
  --outputTransport streamableHttp \
  --streamableHttpPath /mcp \
  --protocolVersion 2025-06-18 \
  --stateful true \
  --sessionTimeout 900000 \
  --healthEndpoint /healthz \
  --healthEndpoint /readyz \
  --logLevel info

See operational docs:

docs/ops/baseline-connector-smoke.md
docs/ops/claude-connector-hardening.md
docs/ops/incident-playbook.md

Smoke scripts:

scripts/smoke/remote-mcp-smoke.sh
scripts/smoke/edge-header-check.sh

OAuth Scaffolding (Phase 2 Prep)

This server now supports optional OAuth discovery/challenge scaffolding for staged rollout:

--http-oauth-resource-metadata-url: when unauthenticated requests are rejected (401), WWW-Authenticate includes:
- Bearer resource_metadata="..."
--http-oauth-protected-resource-path: serves a local OAuth Protected Resource Metadata JSON document.
--http-oauth-authorization-server-issuer: adds authorization_servers to the metadata JSON.
--http-oauth-scopes: adds scopes_supported to the metadata JSON.
--http-oauth-cutover-path: adds a second staged endpoint (for example /mcp-oauth) so you can keep /mcp behavior unchanged while testing auth-required connector cutover.
--http-oauth-cutover-token: token required on the cutover endpoint; if unset, the server falls back to --http-auth-token.

Example:

npx github-mcp-server-kosta \
  --transport http \
  --http-host 127.0.0.1 \
  --http-port 3000 \
  --http-path /mcp \
  --http-auth-token "$MCP_BEARER_TOKEN" \
  --http-oauth-resource-metadata-url "https://connector.example.com/.well-known/oauth-protected-resource" \
  --http-oauth-protected-resource-path "/.well-known/oauth-protected-resource" \
  --http-oauth-authorization-server-issuer "https://auth.example.com" \
  --http-oauth-scopes "mcp.read,mcp.write"

Staged cutover example (/mcp open, /mcp-oauth protected):

npx github-mcp-server-kosta \
  --transport http \
  --http-host 127.0.0.1 \
  --http-port 3000 \
  --http-path /mcp \
  --http-oauth-cutover-path /mcp-oauth \
  --http-oauth-cutover-token "$MCP_CUTOVER_TOKEN"

Important:

This is scaffolding for phased rollout, not a complete OAuth authorization server implementation.
In production Claude.ai connector deployments, the recommended pattern is still edge/gateway-owned OAuth.

Plain-English Security Guidance

If you only ever run this on your own machine and nothing else can reach it, you can usually skip authentication.

If you bind the HTTP server to a network interface that other devices can reach (for example --http-host 0.0.0.0), then anyone who can access that address could potentially use your GitHub token via these tools. In that case you should:

Prefer putting authentication at your gateway (supergateway / Cloudflare / your connector) so the MCP server itself can remain localhost-only.
Or set --http-auth-token so the /mcp endpoint requires a Bearer token.

Response Formats

Most tools support two detail levels:

summary (default) — concise key fields, 5-item previews for lists
detailed — full GitHub API response

Tool Annotations

All tools include MCP annotations to help AI clients make smart decisions:

readOnlyHint — safe to call without side effects
destructiveHint — may modify or delete data (e.g., file updates)
idempotentHint — safe to retry with same arguments
openWorldHint — interacts with external GitHub API

Server Instructions

The server provides workflow guidance to AI models, including:

Tool relationships (e.g., "use github_get_file_content to get SHA before github_create_or_update_file")
Rate limiting info
Token permission requirements
Response mode recommendations

License

MIT License

Author

Kosta Milovanovic (ildunari)

Contributing

Fork the repository
Create your feature branch
Commit your changes
Push to the branch
Create a Pull Request

GitHub