GitHub Team Management MCP Server - Internal Documentation

🎯 What is This?

The GitHub Team Management MCP Server is a comprehensive Model Context Protocol (MCP) server that provides complete GitHub project management automation for AI assistants. Built on Cloudflare Workers, it enables AI agents like Claude and ChatGPT to perform sophisticated GitHub operations including:

📋 Complete Issue Lifecycle Management - Create, comment, assign, label, close/reopen issues
🌳 Advanced Git Operations - Read files, browse directories, create branches, commit changes
📊 Project Board Automation - Manage project boards, assign tasks, update statuses
🔄 Pull Request Management - Create PRs, add comments, track review status
📈 Analytics & Reporting - Financial reports, activity tracking, team analytics

🚀 Why is This Useful?

For Development Teams:

AI-Powered Workflow Automation - Let AI assistants handle routine GitHub tasks
Complete Development Cycle - From issue analysis to PR creation, fully automated
Transparent Operations - All AI commits are co-authored for visibility
Security-First Design - Protected operations prevent dangerous actions

For AI Agents:

Full GitHub API Access - 38+ tools covering every aspect of GitHub management
Intelligent Context - Rich data structures optimized for AI understanding
Safe Operations - Built-in safeguards prevent destructive actions
Cross-Platform Support - Works with Claude, ChatGPT, and other MCP clients

Example AI Workflow:

1. AI analyzes issue from project board
2. AI reads relevant code files
3. AI creates feature branch
4. AI commits code improvements
5. AI creates pull request
6. Human reviews and merges

🔗 Connection URLs & Setup

Production Server

https://team-mcp.efp.workers.dev/sse

Claude desktop

You will have to add the MCP server as a "Connector". Under the "Custom Connectors" section, you will click the "Add custom connector" and enter "https://google-services-mcp.efp.workers.dev/sse"

Cursor IDE

Open Settings → MCP
Click Add Server
Configure:
- Name: GitHub Team Management
- Type: Remote Server
- URL: https://team-mcp.efp.workers.dev/sse

VSCode with Claude Extension

Add to VSCode settings.json:

{
	"claude.mcpServers": [
		{
			"name": "github-team",
			"url": "https://team-mcp.efp.workers.dev/sse"
		}
	]
}

ChatGPT Pro

Go to Settings → Beta Features
Enable Custom Connectors
Navigate to Connectors → Add Connector
Configure:
- Name: GitHub Team Management
- Description: Full GitHub project management with issues, PRs, and project boards
- URL: https://team-mcp.efp.workers.dev/sse

Claude Code CLI

# Install Claude Code
npm install -g @anthropic/claude-code

# Add the server
claude mcp add --transport sse github-team https://team-mcp.efp.workers.dev/sse

# To test connection you have to launch claude code
# run the following command
/mcp

🛠️ Complete Tool Reference (38 Tools)

1. User & Organization Tools (4 tools)

`userInfoOctokit`

Get authenticated user information from GitHub.

Parameters: None
Returns: User profile, repos, followers, etc.

`listOrganizationRepos`

List all repositories for a GitHub organization with filtering.

Parameters: organization, includePrivate, sortBy, limit
Returns: Repository list with metadata

`getRecentActivity`

Get recent activity across organization repositories.

Parameters: organization, days, includePrivate, limit
Returns: Activity summary with commits, issues, PRs

`searchIssuesAndPRs`

Search issues and pull requests across entire organization.

Parameters: organization, query, state, limit
Returns: Filtered issues and PRs matching query

2. Repository Management Tools (9 tools)

`getRepositoryDetails`

Get comprehensive repository information.

Parameters: owner, repo, includeCommits, includeIssues, includePRs, days
Returns: Repository details with recent activity

`getCommitHistory`

Get detailed commit history with filtering.

Parameters: owner, repo, branch, limit, since
Returns: Commit history with author, message, changes

`getContributorStats`

Get contributor statistics for repository.

Parameters: owner, repo
Returns: Contributor list with commit counts

`getRepositoryFile`

Read contents of specific file from repository.

Parameters: owner, repo, path, branch
Returns: File content, encoding, size, SHA

`getRepositoryTree`

Browse file and directory structure.

Parameters: owner, repo, path, branch, recursive
Returns: Directory tree with file metadata

`listRepositoryBranches`

List all branches with commit information.

Parameters: owner, repo, includeProtected
Returns: Branch list with protection status

`getBranchInfo`

Get detailed information about specific branch.

Parameters: owner, repo, branch
Returns: Branch status, ahead/behind counts, protection

`createBranch`

Create new branch from base branch.

Parameters: owner, repo, branchName, baseBranch, description
Returns: New branch details
Security: Validates branch names, prevents protected branch names

`commitChanges`

Commit multiple file changes to branch.

Parameters: owner, repo, branch, message, changes[]
Returns: Commit details with co-author attribution
Security: Blocks protected branches, dangerous paths, delete operations

3. Project Board Management Tools (5 tools)

`listOrganizationProjects`

List all GitHub Projects v2 for organization.

Parameters: organization
Returns: Project list with metadata

`getProjectBoardDetails`

Get complete project board information.

Parameters: includeFields, includeItems, limit
Returns: Project details, fields, items with full metadata

`updateProjectBoardItem`

Update custom field values for project items.

Parameters: itemId, fieldName, value
Returns: Updated field information
Note: Cannot update built-in fields (Title, Assignees, Labels)

`updateProjectBoardDraftIssueTitle`

Update draft issue title and/or description.

Parameters: itemId, title, body
Returns: Updated draft issue details

`createProjectBoardDraftIssue`

Create draft issue directly in project board.

Parameters: title, body, initialStatus
Returns: New draft issue details

4. Issue Management Tools (9 tools)

`createGitHubIssue`

Create new issue with full metadata support.

Parameters: owner, repo, title, body, assignees[], labels[], milestone, addToProject
Returns: Issue details with optional project integration

`commentOnGitHubIssue`

Add comment to existing issue.

Parameters: owner, repo, issueNumber, body
Returns: Comment details

`updateIssueAssignees`

Update issue assignees (replaces existing).

Parameters: owner, repo, issueNumber, assignees[]
Returns: Updated assignee list

`updateIssueLabels`

Update issue labels (replaces existing).

Parameters: owner, repo, issueNumber, labels[]
Returns: Updated label list

`closeIssue`

Close issue with optional reason.

Parameters: owner, repo, issueNumber, reason
Returns: Closure confirmation
Reasons: COMPLETED, NOT_PLANNED

`reopenIssue`

Reopen closed issue.

Parameters: owner, repo, issueNumber
Returns: Reopen confirmation

`updateIssue`

Update issue title and/or body.

Parameters: owner, repo, issueNumber, title, body
Returns: Updated issue details

`getIssueDetails`

Get comprehensive issue information.

Parameters: owner, repo, issueNumber
Returns: Complete issue details with assignees, labels, comments

`addIssueToProject`

Add existing issue to project board.

Parameters: owner, repo, issueNumber, initialStatus
Returns: Project integration details

5. Pull Request Management Tools (3 tools)

`createPullRequest`

Create new pull request.

Parameters: owner, repo, title, head, base, body, draft, maintainerCanModify
Returns: PR details with mergeable state

`commentOnPullRequest`

Add comment to pull request.

Parameters: owner, repo, prNumber, body
Returns: Comment details

`getPullRequestDetails`

Get comprehensive PR information.

Parameters: owner, repo, prNumber
Returns: Complete PR details with reviews, mergeable state

6. Project Board Assignment Tools (4 tools)

`assignProjectBoardItem`

Assign users to project board items.

Parameters: itemId, usernames[]
Returns: Assignment confirmation
Smart Logic: Uses custom fields or falls back to GitHub issue assignment

`unassignProjectBoardItem`

Remove assignees from project board items.

Parameters: itemId, usernames[]
Returns: Unassignment confirmation

`labelProjectBoardItem`

Add labels to project board items.

Parameters: itemId, labels[]
Returns: Label assignment confirmation

`getProjectAssignableUsers`

Get list of users who can be assigned.

Parameters: None
Returns: Available users with avatars

7. Analytics & Reporting Tools (5 tools)

`getEFPDuneStatistics`

Fetch EFP blockchain analytics from Dune.

Parameters: searchQuery
Returns: Real-time blockchain metrics

`getFinancialReportQuick`

Get pre-cached financial report data.

Parameters: quarter, year
Returns: Cached financial data (fast)

`listFinancialReports`

List all available financial reports.

Parameters: None
Returns: Available reports by quarter

`getFinancialReport`

Extract financial data from reports (with OCR).

Parameters: quarter, year, forceRefresh
Returns: Extracted financial data

`compareFinancialReports`

Compare metrics across multiple quarters.

Parameters: quarters[], metrics[]
Returns: Comparative analysis with growth rates

🔧 Local Development Setup

Prerequisites

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

Step 1: Clone & Install

git clone https://github.com/ethereumfollowprotocol/team-mcp.git
cd team-mcp
npm install

Step 2: Cloudflare Setup

# Login to Cloudflare
wrangler login

# Generate types
npm run cf-typegen

Step 3: GitHub OAuth App

Go to GitHub Developer Settings
Create New OAuth App:
- Name: Team MCP Development
- Homepage URL: http://localhost:8787
- Callback URL: http://localhost:8787/callback
Save Client ID and Client Secret

Step 4: Environment Configuration

Create/update wrangler.jsonc:

{
	"name": "team-mcp",
	"main": "src/index.ts",
	"compatibility_date": "2024-01-01",
	"vars": {
		"GITHUB_CLIENT_ID": "your-github-client-id",
		"GITHUB_CLIENT_SECRET": "your-github-client-secret",
		"COOKIE_ENCRYPTION_KEY": "your-base64-encryption-key"
	},
	"kv_namespaces": [
		{
			"binding": "OAUTH_KV",
			"id": "your-kv-namespace-id"
		}
	]
}

Step 5: Development Server

# Start development server
npm run dev

# Server will be available at:
# http://localhost:8787

Step 6: Testing with AI Clients

Use local development URL:

http://localhost:8787/sse

📋 Code Style Guidelines

TypeScript Standards

Strict TypeScript - All types must be explicitly defined
Zod Validation - All tool parameters validated with Zod schemas
Error Handling - Comprehensive try/catch with descriptive messages

File Organization

src/
├── index.ts              # Main MCP server and tool registration
├── github-api-service.ts  # GitHub API methods and business logic
├── github-handler.ts      # OAuth and authentication
├── types.ts              # TypeScript type definitions
├── const.ts              # Constants and configuration
└── utils.ts              # Utility functions

Naming Conventions

Functions: camelCase (e.g., createGitHubIssue)
Variables: camelCase (e.g., githubApi)
Types/Interfaces: PascalCase (e.g., GitHubIssue)
Constants: UPPER_SNAKE_CASE (e.g., PROJECT_BOARD_ID)

Security Patterns

// 1. Always validate branch names
const protectedBranches = ['main', 'master', 'develop', 'staging', 'production']
if (protectedBranches.includes(branchName.toLowerCase())) {
	throw new Error(`Cannot create branch with protected name: ${branchName}`)
}

// 2. Validate file paths
const dangerousPaths = ['.git/', '/.github/workflows/', '.env']
const hasDangerousPath = changes.some(c =>
	dangerousPaths.some(dp => c.path.toLowerCase().includes(dp.toLowerCase()))
)

// 3. Block dangerous operations
const allowedOperations = ['create', 'update'] // No 'delete'

Error Handling Pattern

try {
	const result = await githubApi.someOperation()
	return {
		content: [
			{
				type: 'text',
				text: JSON.stringify(result, null, 2),
			},
		],
	}
} catch (error: any) {
	return {
		content: [
			{
				type: 'text',
				text: `Error performing operation: ${error.message}`,
			},
		],
	}
}

🛡️ Security Guidelines

Operations Allowed ✅

Read Operations: Files, branches, issues, PRs, project boards
Create Operations: Issues, PRs, branches, comments, draft issues
Update Operations: Issue content, labels, assignees, project fields
Branch Creation: From any base branch to any valid name

Operations Blocked ❌

Delete Operations: No files, branches, or repositories can be deleted
Protected Branch Commits: Cannot commit to main/master/develop/staging/production
System File Modification: Cannot modify .git/, workflows, .env, lock files
Force Operations: No force push or history rewriting
Merge Operations: Cannot merge PRs (human-only operation)

Co-Authored Commits

All commits made through commitChanges are automatically co-authored:

Your commit message here

Co-authored-by: GitHub Team MCP <ethid.github.mcp@ethfollow.xyz>

Authentication Flow

OAuth-based - Users authenticate via GitHub OAuth
Token Storage - Encrypted storage in Cloudflare KV
Scope Validation - Required scopes: repo, read:org, read:repo_hook, project

🔍 Troubleshooting

Common Issues

"Authentication Required" Error

Solution:

Ensure GitHub OAuth app is configured correctly
Verify callback URL matches exactly
Check required scopes are granted
Re-authenticate through MCP client

"Tool Not Found" Error

Solution:

Restart MCP client (Claude Desktop/Cursor/VSCode)
Check server URL is accessible: curl -I https://team-mcp.efp.workers.dev/sse
Verify MCP configuration syntax

Rate Limit Errors

Solutions:

GitHub API: 5,000 requests/hour when authenticated
Server includes automatic retry logic
Wait between large operations

TypeScript Compilation Errors

Solution:

# Check for errors
npm run type-check

# Fix common issues
npm run cf-typegen  # Regenerate Cloudflare types

Development Debugging

# View deployment logs
wrangler tail

# Test server endpoint
curl -X GET http://localhost:8787/sse

# Check OAuth flow
curl -I http://localhost:8787/authorize

🚀 Deployment

Production Deployment

# Deploy to Cloudflare Workers
npm run deploy

# Verify deployment
curl -I https://team-mcp.efp.workers.dev/sse

Environment Variables

Required for production:

GITHUB_CLIENT_ID - GitHub OAuth App Client ID
GITHUB_CLIENT_SECRET - GitHub OAuth App Client Secret
COOKIE_ENCRYPTION_KEY - Base64 encoded 32-byte key
DUNE_API_KEY - (Optional) Dune Analytics API key
OCR_SPACE_API_KEY - (Optional) OCR Space API key

🤖 AI Agent Integration Notes

For AI Assistants:

Tool Discovery: All 38 tools are automatically available after connection
Parameter Validation: Zod schemas ensure type safety
Rich Responses: JSON responses optimized for AI parsing
Error Context: Descriptive error messages for debugging

Workflow Recommendations:

Start with Repository Navigation - Use getRepositoryTree and getRepositoryFile
Check Project Status - Use getProjectBoardDetails for current state
Create Feature Workflow - createBranch → commitChanges → createPullRequest
Issue Management - Full lifecycle from creation to closure

Best Practices for AI:

Be Specific - Use exact repository names and paths
Check Context - Read existing code before making changes
Security Aware - Understand what operations are blocked and why
Incremental Changes - Make small, focused commits
Human Oversight - Always create PRs for human review

This MCP server transforms AI assistants into powerful GitHub automation tools while maintaining security and human oversight. Happy coding! 🎉