mcp-github-server

A production-grade Model Context Protocol (MCP) server that gives LLMs deep access to GitHub repositories, issues, pull requests, actions, code search, and more.

Features

• 18 tools for comprehensive GitHub interaction
• Dynamic resources for repos, issues, PRs, and files
• 4 prompt templates for PR review, issue triage, code review, and repo summaries
• GitHub App + Personal Access Token authentication
• Redis caching with in-memory fallback
• Rate limit handling with exponential backoff and jitter
• Full Zod validation on all inputs
• Docker support for containerized deployment

Quick Start

Prerequisites

• Node.js 20+
• A GitHub Personal Access Token or GitHub App credentials

Installation

npm install

Configuration

Copy the example environment file and fill in your credentials:

cp .env.example .env

Required:

GITHUB_TOKEN=ghp_your_personal_access_token

Or for GitHub App authentication:

GITHUB_APP_ID=12345
GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n..."
GITHUB_APP_INSTALLATION_ID=67890

Running

# Development
npm run dev

# Production
npm run build
npm start

Docker

# Build and run with Redis
docker compose up -d

# Or build manually
docker build -t mcp-github-server .
docker run -e GITHUB_TOKEN=ghp_xxx mcp-github-server

MCP Client Configuration

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "github": {
      "command": "node",
      "args": ["/path/to/mcp-github-server/dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token"
      }
    }
  }
}

Tools

Repository Tools

Tool	Description
search_repos	Search GitHub repositories with language, topic, and star filters
get_repo_info	Get detailed repository information including stats and metadata
get_repo_stats	Get contributor stats, commit activity, and code frequency

File Tools

Tool	Description
get_file_content	Read file content from a repository (auto-decodes base64)
list_directory	List directory contents with type sorting
search_code	Search code across repos with language/file/path filters

Issue Tools

Tool	Description
list_issues	List/filter issues with pagination (excludes PRs)
create_issue	Create new issues with labels, assignees, and milestones
get_issue	Get detailed issue info with comments

Pull Request Tools

Tool	Description
list_pull_requests	List PRs with state/branch filtering
get_pull_request	Get PR details with diff, files, and reviews
review_pull_request	Submit PR reviews (approve, request changes, comment)
merge_pull_request	Merge PRs with merge/squash/rebase strategies

Branch Tools

Tool	Description
create_branch	Create branches from ref, branch, or SHA
compare_branches	Compare branches with commit and file diffs

Other Tools

Tool	Description
get_actions_status	Get CI/CD workflow run status with optional job details
manage_labels	Create, update, delete, and list repository labels
get_commit_history	Get commit log with author/path/date filtering

Resources

Dynamic resource templates available via MCP resource protocol:

• github://repos/{owner}/{repo} - Repository details
• github://repos/{owner}/{repo}/readme - Repository README
• github://repos/{owner}/{repo}/languages - Language breakdown
• github://repos/{owner}/{repo}/topics - Repository topics
• github://repos/{owner}/{repo}/issues - Open issues list
• github://repos/{owner}/{repo}/issues/{number} - Issue details
• github://repos/{owner}/{repo}/pulls - Open PRs list
• github://repos/{owner}/{repo}/pulls/{number} - PR details
• github://repos/{owner}/{repo}/contents/{path} - File content
• github://repos/{owner}/{repo}/tree/{path} - Directory listing

Prompts

Prompt	Description
pr_review	Structured PR review with security/performance/architecture focus
issue_triage	Single or batch issue triage with priority classification
code_review	File/directory code review with depth levels
repo_summary	Comprehensive repository health and activity summary

Configuration Reference

Variable	Default	Description
GITHUB_TOKEN	-	Personal access token
GITHUB_APP_ID	-	GitHub App ID
GITHUB_APP_PRIVATE_KEY	-	GitHub App private key
GITHUB_APP_INSTALLATION_ID	-	GitHub App installation ID
REDIS_URL	-	Redis connection URL (optional)
REDIS_KEY_PREFIX	mcp-github:	Redis key prefix
CACHE_TTL_SECONDS	300	Default cache TTL
RATE_LIMIT_MAX_RETRIES	3	Max retries on rate limit
RATE_LIMIT_BASE_DELAY_MS	1000	Base delay for exponential backoff
LOG_LEVEL	info	Logging level
SERVER_NAME	mcp-github-server	Server name
SERVER_VERSION	1.0.0	Server version

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Type check
npm run typecheck

# Lint
npm run lint

# Format
npm run format

Architecture

src/
  index.ts          - Entry point, stdio transport setup
  server.ts         - MCP server with handler registration
  config.ts         - Environment-based configuration
  types.ts          - Shared TypeScript types and Zod schemas
  schema_utils.ts   - Zod-to-JSON-Schema converter
  tools/            - 18 tool implementations with Zod validation
  resources/        - Dynamic resource resolution (repos, issues, PRs, files)
  prompts/          - 4 prompt templates for common workflows
  github/
    client.ts       - Octokit wrapper with caching and retry
    auth.ts         - Token and GitHub App authentication
    rate_limiter.ts - Exponential backoff with jitter
    errors.ts       - Typed GitHub error hierarchy
  cache/
    index.ts        - Cache interface and in-memory implementation
    redis_cache.ts  - Redis-backed cache with TTL

License

MIT