GitHub MCP Server

Model Context Protocol server for GitHub repositories, issues, pull requests, branches, tags, commits, and search.

It ships with 34 tools across 5 categories and supports:

• hosted key-service mode with usr_... user keys
• self-hosted Streamable HTTP deployments
• CLI/stdio usage for local MCP clients

Quick Start

Option 1: Hosted key-service mode

Preferred path-based form:

{
  "mcpServers": {
    "github": {
      "transport": "streamable-http",
      "url": "https://mcp.techmavie.digital/github/mcp/usr_YOUR_USER_KEY"
    }
  }
}

Compatibility query form:

https://mcp.techmavie.digital/github/mcp?api_key=usr_YOUR_USER_KEY

Option 2: Self-hosted HTTP

Use header-based auth on /github/mcp:

{
  "mcpServers": {
    "github": {
      "transport": "streamable-http",
      "url": "https://mcp.techmavie.digital/github/mcp",
      "headers": {
        "X-API-Key": "YOUR_MCP_API_KEY",
        "X-GitHub-Token": "YOUR_GITHUB_TOKEN"
      }
    }
  }
}

MCP_API_KEY must be configured on the server or self-hosted /mcp requests will be rejected. For deployments mounted under /github, set PUBLIC_BASE_PATH=/github so the server card advertises the correct public endpoint.

Option 3: CLI / stdio

npm install -g mcp-github
GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here mcp-github

Example client config:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "mcp-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Option 4: Legacy query-token mode

This is still supported for explicit requests only and is deprecated:

https://mcp.techmavie.digital/github/mcp?token=YOUR_GITHUB_TOKEN

The server no longer falls back to its own GITHUB_PERSONAL_ACCESS_TOKEN for bare /mcp HTTP requests.

Authentication Modes

Mode	Endpoint	Client auth
Hosted key-service	POST /github/mcp/usr_...	user key in path
Hosted key-service compatibility	POST /github/mcp?api_key=usr_...	user key in query string
Self-hosted	POST /github/mcp	X-API-Key and X-GitHub-Token headers
Legacy	POST /github/mcp?token=...	explicit query token, deprecated
CLI	stdio	GITHUB_PERSONAL_ACCESS_TOKEN env var

Tool Categories

Search Tools (3)

• search_repositories
• search_code
• search_users

Repository Tools (12)

• get_repository
• get_commit
• list_commits
• list_branches
• create_or_update_file
• create_repository
• get_file_contents
• fork_repository
• create_branch
• list_tags
• get_tag
• push_files

Issue Tools (7)

• get_issue
• add_issue_comment
• search_issues
• create_issue
• list_issues
• update_issue
• get_issue_comments

Pull Request Tools (11)

• get_pull_request
• update_pull_request
• list_pull_requests
• merge_pull_request
• get_pull_request_files
• get_pull_request_status
• update_pull_request_branch
• get_pull_request_comments
• create_pull_request
• get_pull_request_review_comments
• create_pull_request_review_comment

Utility Tools (1)

• hello

Endpoints

Endpoint	Method	Description
/health	GET	health check
/mcp/:userKey	POST	hosted key-service endpoint
/mcp	POST	self-hosted endpoint
/mcp-debug/open	POST	diagnostics endpoint when enabled
/.well-known/mcp/server-card.json	GET	root-level discovery metadata
/analytics	GET	analytics JSON, requires X-API-Key
/analytics/tools	GET	analytics tool breakdown, requires X-API-Key
/analytics/dashboard	GET	analytics dashboard shell

If this server is mounted under /github, the server-card route still lives at the host root:

https://mcp.techmavie.digital/.well-known/mcp/server-card.json

Environment Variables

Variable	Default	Description
PORT	8080	HTTP port
HOST	0.0.0.0	bind address
GITHUB_PERSONAL_ACCESS_TOKEN	unset	CLI/stdio token only
MCP_API_KEY	unset	required for self-hosted /mcp and analytics
KEY_SERVICE_URL	unset	hosted key-service resolver URL
KEY_SERVICE_TOKEN	unset	hosted key-service bearer token
ALLOWED_ORIGINS	*	comma-separated CORS allowlist
PUBLIC_BASE_PATH	unset	public reverse-proxy mount path such as /github
MCP_PROTOCOL_VERSION	2025-11-25	protocol version reported by HTTP server
MCP_TRACE_HTTP	false	enable sanitized request tracing
ENABLE_MCP_DIAGNOSTICS	false	enable /mcp-debug/open
ANALYTICS_DIR	/app/data	analytics storage directory

Local Development

npm install
npm run dev:http

Build and run production HTTP mode:

npm run build:tsc
npm run start:http

Run CLI mode:

GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here npm run cli

Project Structure

mcp-github/
|-- src/
|   |-- index.ts
|   |-- http-server.ts
|   |-- cli.ts
|   |-- tools/
|   |-- resources/
|-- deploy/
|   |-- DEPLOYMENT.md
|   |-- nginx-mcp.conf
|-- .github/workflows/
|-- docker-compose.yml
|-- Dockerfile
|-- .env.sample
|-- package.json
|-- tsconfig.json
`-- README.md

Security Notes

• Self-hosted /mcp fails closed when MCP_API_KEY is missing.
• Analytics fail closed when MCP_API_KEY is missing.
• Bare /mcp requests no longer inherit the server's own PAT.
• Recent analytics store hashed client IPs only.
• Request-scoped MCP servers and transports are used for HTTP requests.
• ?token= remains available only as an explicit deprecated compatibility path.

License

MIT