GitHub Team Management MCP Server

A comprehensive Model Context Protocol (MCP) server built on Cloudflare Workers that provides full GitHub project management automation for AI assistants. This server enables both Claude and ChatGPT to create issues, manage project boards, assign team members, and automate complete GitHub workflows through OAuth-based authentication.

🚀 Key Features

Complete GitHub Issue Management

• ✅ Create Issues with assignees, labels, and milestones
• ✅ Comment Management - Add comments to any issue
• ✅ Assignee Management - Add/remove assignees from issues
• ✅ Label Management - Apply/remove labels from issues
• ✅ Issue State Control - Close/reopen issues with reasons
• ✅ Content Updates - Modify issue titles and descriptions
• ✅ Project Integration - Automatically add issues to project boards

Advanced Project Board Management

• ✅ Smart Assignment - Assign users to project items (handles both custom fields and built-in GitHub issue assignment)
• ✅ Status Management - Update project board status columns
• ✅ Label Integration - Apply labels to project board items
• ✅ Draft Issue Support - Create and manage draft issues
• ✅ Multi-Item Operations - Bulk operations across project items

Dual AI Assistant Support

• 🤖 Claude Integration - Full feature access through Claude Desktop, Cursor, VSCode
• 🤖 ChatGPT Integration - Compatible with ChatGPT Pro's Deep Research mode
• 🔄 Cross-Compatible - Same server works with both AI assistants
• 📊 Smart Search - AI-optimized search across repositories, issues, and projects

Enterprise Repository Management

• 🏢 Organization-Wide Access - List and analyze all repositories
• 📈 Activity Monitoring - Track commits, issues, PRs across teams
• 👥 Contributor Analytics - Analyze team contributions and patterns
• 🔍 Advanced Search - Find issues/PRs across entire organizations
• 📊 EFP Blockchain Analytics - Real-time Dune Analytics integration

🎯 Perfect For

• Engineering Teams automating GitHub workflows
• Project Managers coordinating development tasks
• DevOps Teams managing multi-repository operations
• AI-Powered Development with Claude or ChatGPT assistance
• Team Leads tracking project progress and assignments

📦 Quick Start

Prerequisites

• Node.js 18+
• Cloudflare Account with Workers plan
• GitHub OAuth App
• Wrangler CLI

1. Setup & Deploy

# Clone and install
git clone <repository-url>
cd team-mcp
npm install

# Login to Cloudflare
wrangler login

# Deploy to Cloudflare Workers
npm run deploy

2. GitHub OAuth Setup

1. Go to GitHub Developer Settings
2. Create "New OAuth App":
   • Name: Your MCP Server
   • URL: https://team-mcp.your-subdomain.workers.dev
   • Callback: https://team-mcp.your-subdomain.workers.dev/callback
3. Save Client ID and Secret

3. Configure Environment

Update wrangler.jsonc:

{
  "vars": {
    "GITHUB_CLIENT_ID": "your-github-client-id",
    "GITHUB_CLIENT_SECRET": "your-github-client-secret",
    "COOKIE_ENCRYPTION_KEY": "your-base64-encryption-key"
  }
}

4. Connect AI Assistant

For Claude Desktop:

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "github-team": {
      "command": "npx",
      "args": ["mcp-remote", "https://team-mcp.your-subdomain.workers.dev/sse"]
    }
  }
}

For ChatGPT Pro:

1. Add custom connector in ChatGPT settings
2. Use URL: https://team-mcp.your-subdomain.workers.dev/sse
3. Test in Deep Research mode

🛠️ Complete Tool Reference

🎫 Issue Management Tools

createGitHubIssue

Create comprehensive GitHub issues with full metadata support.

// Create a bug report with assignees and labels
{
  "owner": "ethereumfollowprotocol",
  "repo": "api",
  "title": "Fix authentication timeout issue",
  "body": "## Bug Description\nUsers experiencing 30s timeout...",
  "assignees": ["janzunec", "teammate"],
  "labels": ["bug", "priority-high"],
  "milestone": 1,
  "addToProject": true
}

Parameters:

• owner (string): Repository owner
• repo (string): Repository name
• title (string): Issue title
• body (string, optional): Issue description in markdown
• assignees (string[], optional): GitHub usernames to assign
• labels (string[], optional): Label names to apply
• milestone (number, optional): Milestone number
• addToProject (boolean, optional): Add to default project board

commentOnGitHubIssue

Add comments to existing GitHub issues.

{
  "owner": "ethereumfollowprotocol",
  "repo": "api",
  "issueNumber": 42,
  "body": "## Update\nThis has been fixed in the latest deployment."
}

updateIssueAssignees

Manage issue assignees (replaces existing assignees).

{
  "owner": "ethereumfollowprotocol",
  "repo": "api",
  "issueNumber": 42,
  "assignees": ["newdev", "teamlead"]
}

updateIssueLabels

Update issue labels (replaces existing labels).

{
  "owner": "ethereumfollowprotocol",
  "repo": "api",
  "issueNumber": 42,
  "labels": ["in-progress", "needs-review"]
}

closeIssue / reopenIssue

Control issue state with optional close reasons.

// Close with reason
{
  "owner": "ethereumfollowprotocol",
  "repo": "api",
  "issueNumber": 42,
  "reason": "COMPLETED"  // or "NOT_PLANNED"
}

// Reopen
{
  "owner": "ethereumfollowprotocol",
  "repo": "api",
  "issueNumber": 42
}

updateIssue

Update issue title and/or description.

{
  "owner": "ethereumfollowprotocol",
  "repo": "api",
  "issueNumber": 42,
  "title": "Updated: Fix authentication timeout issue",
  "body": "## Updated Description\nResolved in version 2.1.0..."
}

getIssueDetails

Fetch comprehensive issue information.

{
  "owner": "ethereumfollowprotocol",
  "repo": "api",
  "issueNumber": 42
}

📋 Project Board Management Tools

getProjectBoardDetails

Get complete project board information including all tasks and custom fields.

{
  "includeFields": true,
  "includeItems": true,
  "limit": 100
}

updateProjectBoardItem

Update custom fields on project board items.

{
  "itemId": "PVTI_lADOCIgXcc4Ah9ZWzgc45F8",
  "fieldName": "Status",
  "value": "In Progress"
}

Supported Status Values:

• "Big Projects", "Throw Backlog", "Jan Backlog", "EIK Backlog"
• "SIWE", "Todo - Jan", "Todo - Throw", "Blocked"
• "In Progress", "Done"

assignProjectBoardItem

Assign team members to project board items.

{
  "itemId": "PVTI_lADOCIgXcc4Ah9ZWzgc45F8",
  "usernames": ["janzunec", "teammate"]
}

Smart Assignment Logic:

• ✅ Works with custom assignee fields in projects
• ✅ Falls back to direct GitHub issue assignment
• ✅ Handles Issues, Pull Requests, and Draft Issues
• ✅ Automatically detects the correct assignment method

unassignProjectBoardItem

Remove specific assignees from project items.

{
  "itemId": "PVTI_lADOCIgXcc4Ah9ZWzgc45F8",
  "usernames": ["former-assignee"]
}

labelProjectBoardItem

Add labels to project board items (works for GitHub issues in projects).

{
  "itemId": "PVTI_lADOCIgXcc4Ah9ZWzgc45F8",
  "labels": ["urgent", "bug"]
}

addIssueToProject

Add existing GitHub issues to the project board.

{
  "owner": "ethereumfollowprotocol",
  "repo": "api",
  "issueNumber": 42,
  "initialStatus": "Todo - Jan"
}

createProjectBoardDraftIssue

Create draft issues directly in the project board.

{
  "title": "Research new API architecture",
  "body": "## Research Goals\n- Evaluate GraphQL vs REST\n- Performance testing",
  "initialStatus": "Big Projects"
}

updateProjectBoardDraftIssueTitle

Update draft issue titles and descriptions.

{
  "itemId": "PVTI_lADOCIgXcc4Ah9ZWzgc45F8",
  "title": "Updated: Research new API architecture",
  "body": "## Updated Research Goals\n- Focus on GraphQL performance"
}

getProjectAssignableUsers

Get list of team members who can be assigned to project items.

// No parameters needed
{
}

🔍 Search & Discovery Tools

search (ChatGPT Compatible)

AI-optimized search across repositories, issues, PRs, and project items.

{
  "query": "authentication bug"
}

Search Types:

• 🔍 Repository search (when query includes "repo" or is short)
• 🎫 Issue/PR search (full GitHub search syntax)
• 📋 Project item search (when query includes "project", "task", "board")

fetch (ChatGPT Compatible)

Fetch detailed information for specific records by ID.

{
  "id": "repo:ethereumfollowprotocol/api"
}
// or
{
  "id": "issue:ethereumfollowprotocol:api:42"
}
// or
{
  "id": "project-item:PVTI_lADOCIgXcc4Ah9ZWzgc45F8"
}

Supported ID Formats:

• repo:owner/name - Repository details
• issue:owner:repo:number - Issue details
• pr:owner:repo:number - Pull request details
• project-item:itemId - Project board item details

🏢 Organization & Repository Tools

listOrganizationRepos

List and filter organization repositories.

{
  "organization": "ethereumfollowprotocol",
  "includePrivate": true,
  "sortBy": "updated",
  "limit": 25
}

getRepositoryDetails

Get comprehensive repository information including recent activity.

{
  "owner": "ethereumfollowprotocol",
  "repo": "api",
  "includeCommits": true,
  "includeIssues": true,
  "includePRs": true,
  "days": 30
}

getRecentActivity

Monitor recent activity across organization repositories.

{
  "organization": "ethereumfollowprotocol",
  "days": 7,
  "includePrivate": true,
  "limit": 20
}

searchIssuesAndPRs

Search issues and pull requests across the entire organization.

{
  "organization": "ethereumfollowprotocol",
  "query": "is:issue is:open label:bug",
  "state": "open",
  "limit": 50
}

GitHub Search Query Examples:

• "author:username" - Items by specific author
• "label:urgent" - Items with specific label
• "is:pr is:open" - Open pull requests only
• "bug in:title" - "Bug" in title
• "created:>2024-01-01" - Created after date

📊 Analytics & Statistics

getEFPDuneStatistics

Access real-time EFP (Ethereum Follow Protocol) blockchain analytics.

{
  "searchQuery": "minted"  // Filter for minting statistics
}
// or
{
  "searchQuery": "daily"   // Daily metrics
}
// or
{}  // All 26+ available statistics

Available Metrics:

• User growth and adoption trends
• Token minting statistics (all chains)
• Transaction volume analytics
• Daily/monthly active users
• Protocol usage patterns

🔒 Security & Authentication

OAuth Security Model

• 🔐 Encrypted Token Storage in Cloudflare KV
• 🍪 Secure Cookie Handling with HTTP-only flags
• 🔑 Minimal Scope Permissions - only necessary GitHub scopes
• 🛡️ Rate Limit Protection with automatic retry logic
• 🔒 HTTPS Enforced - all communications encrypted

Required GitHub Permissions

{
  "scopes": [
    "repo", // Repository access (read/write)
    "read:org", // Organization information
    "read:repo_hook", // Repository webhooks
    "project" // GitHub Projects v2 (read/write)
  ]
}

Access Control

• ✅ User-based authentication via GitHub OAuth
• ✅ Organization membership validation
• ✅ Repository-level permissions respected
• ✅ Project board access control enforced

🎛️ Configuration

Environment Variables

# Required
GITHUB_CLIENT_ID=your_github_oauth_client_id
GITHUB_CLIENT_SECRET=your_github_oauth_client_secret
COOKIE_ENCRYPTION_KEY=base64_encoded_32_byte_key

# Optional
DUNE_API_KEY=your_dune_analytics_api_key
OCR_SPACE_API_KEY=your_ocr_space_api_key

Project Configuration

Update src/const.ts to customize:

export const PROJECT_BOARD_ID = 'PVT_kwDOCIgXcc4Ah9ZW';

export const PROJECT_STATUSES = [
  'Big Projects',
  'Throw Backlog',
  'Jan Backlog',
  'EIK Backlog',
  'SIWE',
  'Todo - Jan',
  'Todo - Throw',
  'Blocked',
  'In Progress',
  'Done',
] as const;

📊 Performance & Optimization

Caching Strategy

• ⚡ 5-minute API response caching for GitHub data
• 🚀 Intelligent cache invalidation on updates
• 📈 Rate limit optimization with automatic backoff
• 🔄 Parallel API calls for bulk operations

Rate Limit Management

• 📊 GitHub API: 5,000 requests/hour (authenticated)
• 📊 Dune Analytics: Based on plan (40-1000 requests/minute)
• 🔄 Automatic retry logic with exponential backoff
• ⚡ Request batching for efficiency

🚨 Troubleshooting

Common Issues

Authentication Fails

# Check OAuth configuration
curl -I https://your-worker.workers.dev/sse
# Verify GitHub OAuth app callback URL matches exactly

Rate Limit Errors

• ✅ GitHub API provides 5,000 requests/hour when authenticated
• ✅ Server implements automatic retry with backoff
• ✅ Check remaining quota: included in error messages

Tool Not Found

• ✅ Ensure you're using the correct tool name
• ✅ Check MCP client connection status
• ✅ Verify OAuth authentication completed

Project Board Access

// Check if item exists
{
  "includeItems": true,
  "limit": 200
}
// Use getProjectBoardDetails to see all available items

Debug Commands

# View deployment logs
wrangler tail

# Test server endpoint
curl -X GET https://your-worker.workers.dev/sse

# Check OAuth flow
curl -I https://your-worker.workers.dev/authorize

🤝 Multi-Client Compatibility

Claude Integration

• ✅ Full Feature Access - All tools available
• ✅ Native OAuth - Seamless authentication
• ✅ Rich Responses - Detailed JSON formatting
• ✅ Workflow Integration - Perfect for development automation

ChatGPT Integration

• ✅ Deep Research Mode - Optimized for ChatGPT Pro
• ✅ Search & Fetch - Required ChatGPT tools implemented
• ✅ Read-Only Safe - Respects current ChatGPT limitations
• ✅ Future Ready - Will support write operations when available

Universal Compatibility

• 🔄 Same Server works with both AI assistants
• 📊 Optimized Responses for each client type
• 🛠️ Backward Compatible - No breaking changes
• 🚀 Future Proof - Ready for new MCP clients

🔮 Roadmap

Next Features

• 🔄 Webhook Support for real-time updates
• 📊 Enhanced Analytics with custom dashboards
• 🔒 Team-based Access Control with role management
• 🤖 AI Workflow Automation with smart suggestions
• 📱 Mobile Optimization for MCP mobile clients

Integration Expansion

• 🐙 GitLab Support - Multi-platform repository management
• 📈 Linear Integration - Issue tracking across platforms
• 💬 Slack/Discord - Team notification integration
• 📊 Jira Sync - Enterprise project management

📄 License

MIT License - See LICENSE file for details.

🆘 Support

• 🐛 Issues: GitHub Issues
• 📖 Documentation: This README + inline tool descriptions
• 🚀 Cloudflare Docs: Workers Documentation
• 🤖 MCP Protocol: Model Context Protocol

---

🎯 Built for modern AI-powered development teams who need comprehensive GitHub automation with both Claude and ChatGPT integration.

This MCP server transforms how AI assistants interact with GitHub, enabling full project management automation while maintaining enterprise-grade security and performance.