# 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**
```bash
# 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](https://github.com/settings/developers)
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`:
```json
{
"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`:
```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.
```javascript
// 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.
```javascript
{
"owner": "ethereumfollowprotocol",
"repo": "api",
"issueNumber": 42,
"body": "## Update\nThis has been fixed in the latest deployment."
}
```
#### **`updateIssueAssignees`**
Manage issue assignees (replaces existing assignees).
```javascript
{
"owner": "ethereumfollowprotocol",
"repo": "api",
"issueNumber": 42,
"assignees": ["newdev", "teamlead"]
}
```
#### **`updateIssueLabels`**
Update issue labels (replaces existing labels).
```javascript
{
"owner": "ethereumfollowprotocol",
"repo": "api",
"issueNumber": 42,
"labels": ["in-progress", "needs-review"]
}
```
#### **`closeIssue`** / **`reopenIssue`**
Control issue state with optional close reasons.
```javascript
// 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.
```javascript
{
"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.
```javascript
{
"owner": "ethereumfollowprotocol",
"repo": "api",
"issueNumber": 42
}
```
### **📋 Project Board Management Tools**
#### **`getProjectBoardDetails`**
Get complete project board information including all tasks and custom fields.
```javascript
{
"includeFields": true,
"includeItems": true,
"limit": 100
}
```
#### **`updateProjectBoardItem`**
Update custom fields on project board items.
```javascript
{
"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.
```javascript
{
"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.
```javascript
{
"itemId": "PVTI_lADOCIgXcc4Ah9ZWzgc45F8",
"usernames": ["former-assignee"]
}
```
#### **`labelProjectBoardItem`**
Add labels to project board items (works for GitHub issues in projects).
```javascript
{
"itemId": "PVTI_lADOCIgXcc4Ah9ZWzgc45F8",
"labels": ["urgent", "bug"]
}
```
#### **`addIssueToProject`**
Add existing GitHub issues to the project board.
```javascript
{
"owner": "ethereumfollowprotocol",
"repo": "api",
"issueNumber": 42,
"initialStatus": "Todo - Jan"
}
```
#### **`createProjectBoardDraftIssue`**
Create draft issues directly in the project board.
```javascript
{
"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.
```javascript
{
"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.
```javascript
// No parameters needed
{
}
```
### **🔍 Search & Discovery Tools**
#### **`search`** (ChatGPT Compatible)
AI-optimized search across repositories, issues, PRs, and project items.
```javascript
{
"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.
```javascript
{
"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.
```javascript
{
"organization": "ethereumfollowprotocol",
"includePrivate": true,
"sortBy": "updated",
"limit": 25
}
```
#### **`getRepositoryDetails`**
Get comprehensive repository information including recent activity.
```javascript
{
"owner": "ethereumfollowprotocol",
"repo": "api",
"includeCommits": true,
"includeIssues": true,
"includePRs": true,
"days": 30
}
```
#### **`getRecentActivity`**
Monitor recent activity across organization repositories.
```javascript
{
"organization": "ethereumfollowprotocol",
"days": 7,
"includePrivate": true,
"limit": 20
}
```
#### **`searchIssuesAndPRs`**
Search issues and pull requests across the entire organization.
```javascript
{
"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.
```javascript
{
"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**
```json
{
"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**
```bash
# 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:
```typescript
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**
```bash
# 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**
```javascript
// Check if item exists
{
"includeItems": true,
"limit": 200
}
// Use getProjectBoardDetails to see all available items
```
### **Debug Commands**
```bash
# 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](LICENSE) file for details.
## 🆘 **Support**
- 🐛 **Issues**: [GitHub Issues](https://github.com/ethereumfollowprotocol/team-mcp/issues)
- 📖 **Documentation**: This README + inline tool descriptions
- 🚀 **Cloudflare Docs**: [Workers Documentation](https://developers.cloudflare.com/workers/)
- 🤖 **MCP Protocol**: [Model Context Protocol](https://modelcontextprotocol.io/)
---
**🎯 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._
