GitHub Issues MCP

A remote MCP server on Cloudflare Workers that lets Claude (or any MCP client) manage GitHub Issues, labels, and milestones on authorized repositories.

Authentication is handled via GitHub OAuth, so Claude.ai connects natively without workarounds. The OAuth token obtained during login is reused for GitHub API calls — no separate Personal Access Token needed.

This server is part of Token Brain, a personal knowledge and agent infrastructure built around Claude.

Features

• Issues: list, create, update, and comment on issues
• Labels: list and create labels with colors and descriptions
• Milestones: list and create milestones with due dates
• Repository scoping: restrict access to a configurable list of authorized repos
• Single-owner access: GitHub OAuth scope guard restricts access to one authorized user
• Health check: alive tool to verify the server and OAuth are operational

Tools

Tool	Description
alive	Health check — confirms the server is running and authentication is valid
list_repos	List authorized repositories with metadata
list_issues	List issues with filters (state, labels, milestone, assignee)
get_issue	Get full issue details including all comments
create_issue	Create a new issue with title, body, labels, milestone, assignees
update_issue	Update an existing issue (title, body, state, labels, milestone)
add_issue_comment	Add a comment to an issue (supports Markdown)
list_labels	List all labels on a repository
create_label	Create a new label with name, color, and description
list_milestones	List milestones with open/closed issue counts
create_milestone	Create a new milestone with title, description, and due date
help	Usage guide listing all available tools with examples

Prerequisites

• Node.js (v18+)
• A Cloudflare account (free plan works)
• A GitHub OAuth App for authentication

Quick Start

# Clone and install
git clone https://github.com/your-username/mcp-github-issues.git
cd mcp-github-issues
npm install

# Configure
cp .env.example .env
# Edit .env with your values (see Configuration below)

# Create Cloudflare resources
wrangler kv namespace create OAUTH_KV
# Copy the returned ID into wrangler.jsonc

# Set production secrets
wrangler secret put GITHUB_CLIENT_ID
wrangler secret put GITHUB_CLIENT_SECRET
wrangler secret put COOKIE_ENCRYPTION_KEY
wrangler secret put ALLOWED_GITHUB_ID
wrangler secret put ALLOWED_GITHUB_LOGIN

# Deploy
wrangler deploy

Your MCP endpoint will be available at https://your-worker.your-subdomain.workers.dev/mcp.

Configuration

Environment Variables

Variable	Description
GITHUB_CLIENT_ID	GitHub OAuth App client ID
GITHUB_CLIENT_SECRET	GitHub OAuth App client secret
COOKIE_ENCRYPTION_KEY	Random 64-char hex string for cookie encryption
ALLOWED_GITHUB_ID	Your GitHub user ID (integer)
ALLOWED_GITHUB_LOGIN	Your GitHub username

wrangler.jsonc Variables

Variable	Description
ALLOWED_REPOS	Comma-separated list of owner/repo the server can access

GitHub OAuth App Setup

1. Go to GitHub Developer Settings
2. Create a new OAuth App
3. Set the Authorization callback URL to https://your-worker.your-subdomain.workers.dev/callback
4. Important: request the repo scope (full repository access for issues, labels, milestones)
5. Copy the Client ID and Client Secret into your secrets

Authorized Repositories

Edit the ALLOWED_REPOS variable in wrangler.jsonc to control which repositories the server can access:

"vars": {
  "ALLOWED_REPOS": "your-username/repo-one,your-username/repo-two"
}

Connecting to Claude.ai

1. In Claude.ai, go to Settings > Integrations
2. Add a custom MCP server
3. Enter your Worker URL: https://your-worker.your-subdomain.workers.dev/mcp
4. Claude will redirect you to GitHub for authentication
5. Once authorized, the issue management tools appear in your conversation

Architecture

The server runs on Cloudflare Workers and uses:

• KV for OAuth session management
• workers-oauth-provider for the OAuth 2.1 flow
• MCP SDK (@modelcontextprotocol/sdk) for tool registration and transport
• GitHub REST API for all issue operations (proxied through the Worker)

The server is stateless — it doesn't store any issue data. Every tool call makes a real-time request to the GitHub API using the OAuth token obtained during authentication.

Helper Scripts

The scripts/ directory includes shell scripts for managing authorized repositories:

# Add a repository to the authorized list
./scripts/add-repo.sh owner/repo-name

# Remove a repository from the authorized list
./scripts/remove-repo.sh owner/repo-name

License

MIT — see LICENSE.