MCP GitHub Project Manager

Option 1: Install from npm (recommended)

# Install the package globally npm install -g mcp-github-project-manager # Or install in your project npm install mcp-github-project-manager

# Clone the repository git clone https://github.com/kunwarVivek/mcp-github-project-manager.git cd mcp-github-project-manager # Install dependencies npm install # or pnpm install # Build the project npm run build

# Copy the example environment file cp .env.example .env # Edit .env with your GitHub token and details

GITHUB_TOKEN=your_github_token GITHUB_OWNER=repository_owner GITHUB_REPO=repository_name

The GitHub token requires these permissions:

- repo(Full repository access)
- project(Project access)
- write:org(Organization access)

At least one AI provider is required for AI-powered features:

# Primary AI providers (at least one required) ANTHROPIC_API_KEY=your_anthropic_api_key_here OPENAI_API_KEY=your_openai_api_key_here GOOGLE_API_KEY=your_google_api_key_here PERPLEXITY_API_KEY=your_perplexity_api_key_here # AI Model Configuration (optional - uses defaults if not specified) AI_MAIN_MODEL=claude-3-5-sonnet-20241022 AI_RESEARCH_MODEL=perplexity-llama-3.1-sonar-large-128k-online AI_FALLBACK_MODEL=gpt-4o AI_PRD_MODEL=claude-3-5-sonnet-20241022 # AI Task Generation Configuration (optional) MAX_TASKS_PER_PRD=50 DEFAULT_COMPLEXITY_THRESHOLD=7 MAX_SUBTASK_DEPTH=3 AUTO_DEPENDENCY_DETECTION=true AUTO_EFFORT_ESTIMATION=true # Enhanced Task Context Generation Configuration (optional) ENHANCED_TASK_GENERATION=true AUTO_CREATE_TRACEABILITY=true AUTO_GENERATE_USE_CASES=true AUTO_CREATE_LIFECYCLE=true ENHANCED_CONTEXT_LEVEL=standard INCLUDE_BUSINESS_CONTEXT=false INCLUDE_TECHNICAL_CONTEXT=false INCLUDE_IMPLEMENTATION_GUIDANCE=false

- Sign up at](https://github.com/HarshKumarSharma/MCP/blob/HEAD/DOCKER.md)Anthropic Console
- Create an API key
- SetANTHROPIC_API_KEYin your environment
- Sign up atOpenAI Platform
- Create an API key
- SetOPENAI_API_KEYin your environment
- Sign up atGoogle AI Studio
- Create an API key
- SetGOOGLE_API_KEYin your environment
- Sign up atPerplexity API
- Create an API key
- SetPERPLEXITY_API_KEYin your environment

# Start the MCP server using stdio transport mcp-github-project-manager # Start with environment variables GITHUB_TOKEN=your_token mcp-github-project-manager # Start with command line arguments mcp-github-project-manager --token=your_token --owner=your_username --repo=your_repo # Use a specific .env file mcp-github-project-manager --env-file=.env.production # Show verbose output mcp-github-project-manager --verbose # Display help information mcp-github-project-manager --help

# Run directly with ts-node node --loader ts-node/esm src/index.ts # Run with command line arguments node --loader ts-node/esm src/index.ts --token=your_token --owner=your_username --repo=your_repo # Use the npm dev script (watches for changes) npm run dev # Display help information node --loader ts-node/esm src/index.ts --help

import { Server } from "mcp-github-project-manager"; // Create and start an MCP server instance const server = new Server({ transport: "stdio", // or "http" for HTTP server config: { githubToken: process.env.GITHUB_TOKEN, githubOwner: process.env.GITHUB_OWNER, githubRepo: process.env.GITHUB_REPO } }); server.start();

// Example using an MCP client library import { McpClient } from "@modelcontextprotocol/client"; import { spawn } from "child_process"; // Create a child process running the MCP server const serverProcess = spawn("mcp-github-project-manager", [], { env: { ...process.env, GITHUB_TOKEN: "your_token" } }); // Connect the MCP client to the server const client = new McpClient({ transport: { type: "process", process: serverProcess } }); // Call MCP tools const result = await client.callTool("create_project", { title: "My Project", description: "A new GitHub project" });

For more examples, see theUser Guideand theexamples/directory.

# 1. Generate PRD from project idea generate_prd({ "projectIdea": "AI-powered task management system with real-time collaboration", "projectName": "TaskAI Pro", "author": "product-team", "complexity": "high", "timeline": "6 months", "includeResearch": true }) # 2. Parse PRD and generate tasks with traceability parse_prd({ "prdContent": "<generated PRD content>", "maxTasks": 30, "createTraceabilityMatrix": true, "includeUseCases": true, "projectId": "task-ai-pro" }) # 3. Get next task recommendations get_next_task({ "sprintCapacity": 40, "teamSkills": ["react", "node.js", "typescript"], "maxComplexity": 7, "includeAnalysis": true }) # 4. Analyze complex tasks analyze_task_complexity({ "taskTitle": "Implement real-time collaboration", "taskDescription": "Build WebSocket-based real-time collaboration with conflict resolution", "teamExperience": "mixed", "includeBreakdown": true, "includeRisks": true }) # 5. Break down complex tasks expand_task({ "taskTitle": "Build analytics dashboard", "taskDescription": "Create comprehensive analytics dashboard with AI insights", "currentComplexity": 8, "targetComplexity": 3, "includeEstimates": true, "includeDependencies": true })

# Add new feature with complete lifecycle add_feature({ "featureIdea": "Advanced Analytics Dashboard", "description": "Real-time analytics with custom charts and AI-powered insights", "requestedBy": "product-manager", "businessJustification": "Increase user engagement and provide actionable insights", "targetUsers": ["project-managers", "team-leads", "executives"], "autoApprove": true, "expandToTasks": true, "createLifecycle": true }) # This automatically creates: # ✅ Business requirement analysis # ✅ Use cases with actor-goal-scenario structure # ✅ Tasks with complete traceability links # ✅ Lifecycle tracking for all tasks

# Create comprehensive traceability matrix create_traceability_matrix({ "projectId": "task-ai-pro", "prdContent": "<PRD content>", "features": [...], "tasks": [...], "validateCompleteness": true }) # Output includes: # ✅ Business Requirements → Features → Use Cases → Tasks # ✅ Bidirectional traceability links # ✅ Coverage analysis with gap identification # ✅ Orphaned task detection # ✅ Unimplemented requirement tracking

# Default: Traceability-based context (fast, no AI required) parse_prd({ "prdContent": "<PRD content>", "enhancedGeneration": true, "contextLevel": "standard" }) # Enhanced: AI-powered comprehensive context parse_prd({ "prdContent": "<PRD content>", "enhancedGeneration": true, "contextLevel": "full", "includeBusinessContext": true, "includeTechnicalContext": true, "includeImplementationGuidance": true }) # Performance optimized: Minimal context for speed parse_prd({ "prdContent": "<PRD content>", "enhancedGeneration": true, "contextLevel": "minimal", "includeBusinessContext": false, "includeTechnicalContext": false, "includeImplementationGuidance": false })

- Minimal: Basic traceability context only (fastest)
- Standard: Traceability + basic business context (default)
- Full: Complete AI-enhanced context with implementation guidance

- Business Context: Why the task matters, user impact, success metrics
- Feature Context: Parent feature information, user stories, business value
- Technical Context: Constraints, architecture decisions, integration points
- Implementation Guidance: Step-by-step recommendations, best practices, pitfalls
- Enhanced Acceptance Criteria: Detailed verification methods and priorities
- Contextual References: Links to relevant PRD sections and technical specs

The enhanced context generation functionality includes comprehensive test coverage:

- src/__tests__/TaskContextGenerationService.test.ts- Core context generation service tests
- src/__tests__/TaskGenerationService.enhanced.test.ts- Enhanced task generation integration tests
- src/__tests__/ParsePRDTool.enhanced.test.ts- Tool-level context generation tests

- Traceability-based context generation(default behavior)
- AI-enhanced context generation(when AI is available)
- Graceful fallbackwhen AI services are unavailable
- Configuration validationand environment variable handling
- Error handlingand resilience testing
- Integration testingwith existing task generation pipeline

# Run all AI-related tests (includes context generation) npm run test:ai # Run specific context generation tests npm test -- --testPathPattern="TaskContextGeneration" npm test -- --testPathPattern="enhanced" # Run all tests npm test

The MCP GitHub Project Manager includes a comprehensive end-to-end testing suite that tests all MCP tools through the actual MCP interface with both mocked and real API calls.

- ✅40+ GitHub Project Management Tools- Complete CRUD operations for projects, milestones, issues, sprints, labels, and more
- ✅8 AI Task Management Tools- PRD generation, task parsing, complexity analysis, feature management, and traceability
- ✅Complex Workflow Integration- Multi-tool workflows and real-world project management scenarios
- ✅Real API Testing- Optional testing with actual GitHub and AI APIs
- ✅Schema Validation- Comprehensive argument validation for all tools
- ✅Error Handling- Graceful error handling and recovery testing

# Run comprehensive E2E tests (mocked APIs) npm run test:e2e:tools # Run with real APIs (requires credentials) npm run test:e2e:tools:real # Use the interactive test runner npm run test:e2e:runner # Run specific test categories npm run test:e2e:tools:github # GitHub tools only npm run test:e2e:tools:ai # AI tools only npm run test:e2e:tools:workflows # Integration workflows

# Interactive test runner with options node scripts/run-e2e-tests.js --help # Examples: node scripts/run-e2e-tests.js --real-api --github-only node scripts/run-e2e-tests.js --build --verbose --timeout 120 node scripts/run-e2e-tests.js --ai-only --real-api

GITHUB_TOKEN=ghp_your_github_token GITHUB_OWNER=your-github-username GITHUB_REPO=your-test-repository

# At least one AI API key required ANTHROPIC_API_KEY=sk-ant-your-anthropic-key OPENAI_API_KEY=sk-your-openai-key GOOGLE_API_KEY=your-google-ai-key PERPLEXITY_API_KEY=pplx-your-perplexity-key

E2E_REAL_API=true npm run test:e2e:tools:real

- Tool Registration Validation- Verify all tools are properly registered with correct schemas
- MCP Protocol Compliance- Ensure all tools follow MCP specification
- Response Format Validation- Validate tool responses match expected formats
- Workflow Integration Testing- Test complex multi-tool workflows
- Credential Management- Graceful handling of missing credentials
- Performance Monitoring- Track tool execution performance
- Comprehensive Error Testing- Validate error handling and recovery

- 📖Comprehensive E2E Testing Guide- Detailed testing documentation
- 🔧Test Configuration- Jest configuration for E2E tests
- 🛠️Test Utilities- Reusable test utilities

{ "mcpServers": { "github-project-manager": { "command": "npx", "args": ["-y", "mcp-github-project-manager"], "env": { "GITHUB_TOKEN": "your_github_token", "GITHUB_OWNER": "your_username", "GITHUB_REPO": "your_repo", "ANTHROPIC_API_KEY": "your_anthropic_api_key", "OPENAI_API_KEY": "your_openai_api_key", "GOOGLE_API_KEY": "your_google_api_key", "PERPLEXITY_API_KEY": "your_perplexity_api_key" } } } }

claude mcp add github-project-manager -- npx -y mcp-github-project-manager

{ "mcpServers": { "github-project-manager": { "command": "npx", "args": ["-y", "mcp-github-project-manager"], "env": { "GITHUB_TOKEN": "your_github_token", "GITHUB_OWNER": "your_username", "GITHUB_REPO": "your_repo" } } } }

Add this to your Windsurf MCP config file:

{ "mcpServers": { "github-project-manager": { "command": "npx", "args": ["-y", "mcp-github-project-manager"], "env": { "GITHUB_TOKEN": "your_github_token", "GITHUB_OWNER": "your_username", "GITHUB_REPO": "your_repo" } } } }

SeeWindsurf MCP docsfor more information.

{ "servers": { "github-project-manager": { "type": "stdio", "command": "npx", "args": ["-y", "mcp-github-project-manager"], "env": { "GITHUB_TOKEN": "your_github_token", "GITHUB_OWNER": "your_username", "GITHUB_REPO": "your_repo" } } } }

SeeVS Code MCP docsfor more information.

{ "mcpServers": { "github-project-manager": { "command": "npx", "args": ["-y", "mcp-github-project-manager"], "env": { "GITHUB_TOKEN": "your_github_token", "GITHUB_OWNER": "your_username", "GITHUB_REPO": "your_repo" } } } }

SeeCursor MCP docsfor more information.

FROM node:18-alpine WORKDIR /app # Install the package globally RUN npm install -g mcp-github-project-manager # Default command to run the server CMD ["mcp-github-project-manager"]

docker build -t github-project-manager-mcp .

Update your MCP client's configuration to use the Docker command:

{ "mcpServers": { "github-project-manager": { "command": "docker", "args": ["run", "-i", "--rm", "github-project-manager-mcp"], "env": { "GITHUB_TOKEN": "your_github_token", "GITHUB_OWNER": "your_username", "GITHUB_REPO": "your_repo" } } } }

If you encounter module resolution issues, try usingbunxinstead ofnpx:

{ "mcpServers": { "github-project-manager": { "command": "bunx", "args": ["-y", "mcp-github-project-manager"] } } }

On Windows, you may need to usecmdto run the command:

{ "mcpServers": { "github-project-manager": { "command": "cmd", "args": [ "/c", "npx", "-y", "mcp-github-project-manager" ] } } }

If you encounter permission issues, make sure your GitHub token has the required permissions listed in the Configuration section.