GitHub

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.

- 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

# 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

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

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

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

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"] } } }

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

- In--tool-mode lazy, the server only exposes bootstrap tools plus any preloaded groups (default:core,search).
- Load additional groups at runtime usinggithub_tool_groups_load(e.g.,issues,pulls,rest).
- The server advertisestools.listChanged: trueand emitsnotifications/tools/list_changedafter loading groups, but some MCP clients may not auto-refresh tool lists. If your client does not, calltools/listagain (or restart the session).

- --transport httpexposes a single MCP endpoint (defaulthttp://127.0.0.1:3000/mcp) supportingGET,POST, andDELETE.
- By default the server binds to127.0.0.1for safety. If you bind to0.0.0.0or another interface, you should set--http-auth-tokenand strongly consider--http-allowed-hostsand--http-allowed-origins.
- In HTTP mode, lazy tool loading state is session-isolated: eachMcp-Session-Idgets its own tool-group load state.
- Optional stricter startup guard:--http-require-auth-on-public-bind truerefuses startup when binding non-localhost without--http-auth-token.

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

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

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

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

- --http-oauth-resource-metadata-url: when unauthenticated requests are rejected (401),WWW-Authenticateincludes:

- Bearer resource_metadata="..."

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 (/mcpopen,/mcp-oauthprotected):

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"

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

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-tokenso the/mcpendpoint requires a Bearer token.

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

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

The server provides workflow guidance to AI models, including:

- Tool relationships (e.g., "usegithub_get_file_contentto get SHA beforegithub_create_or_update_file")
- Rate limiting info
- Token permission requirements
- Response mode recommendations
- Fork the repository
- Create your feature branch
- Commit your changes
- Push to the branch
- Create a Pull Request

A portable MCP server for performing various GitHub operations on any repository.

Interact with the GitHub API for repository management, file operations, and search.

Interact with GitHub repositories, including file operations, repository management, and search.

Integrates with the GitHub API for automation and interaction with repositories.

Integrate GitHub functionalities into AI assistants using the GitHub CLI.

A powerful GitHub automation and management tool providing a comprehensive API wrapper for GitHub operations.

Hosted, Stateless & Multitenant GitHub MCP server connects AI tools directly to GitHub's platform

A CLI for interacting with GitKraken APIs. Includes an MCP server via gk mcp that not only wraps GitKraken APIs, but also Jira, GitHub, GitLab, and more.

Creates commit messages from staged files in a local git repository.

An MCP server for interacting with the AtomGit API for version control and code hosting.