team-mcp by ethereumfollowprotocol - MCP Server

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

Go to GitHub Developer Settings
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
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:

Add custom connector in ChatGPT settings
Use URL: https://team-mcp.your-subdomain.workers.dev/sse
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 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.