Provides comprehensive GitHub project management through GitHub's GraphQL API, allowing creation and management of projects, issues, milestones, sprints, and labels with bidirectional synchronization.
Incorporates Google Gemini's AI capabilities for project management assistance and task analysis.
Utilizes OpenAI's models as an alternative provider with fallback support for AI-powered task generation and analysis.
Integrates Perplexity's AI for research and analysis tasks within the project management workflow.
MCP GitHub Project Manager
A comprehensive Model Context Protocol (MCP) server that provides advanced GitHub project management capabilities with AI-powered task management and complete requirements traceability. Transform your project ideas into actionable tasks with full end-to-end tracking from business requirements to implementation.
Overview
This server implements the Model Context Protocol to provide comprehensive GitHub project management with advanced AI capabilities. Beyond traditional project management, it offers AI-powered task generation, requirements traceability, and intelligent project planning through GitHub's GraphQL API while maintaining state and handling errors according to MCP specifications.
๐ What Makes This Special
AI-Powered: Transform project ideas into comprehensive PRDs and actionable tasks using multiple AI providers
Complete Traceability: Full end-to-end tracking from business requirements โ features โ use cases โ tasks
Intelligent Analysis: AI-powered complexity analysis, effort estimation, and task recommendations
Professional Standards: IEEE 830 compliant requirements documentation with enterprise-grade change management
Table of Contents
Quick Start
Using NPM
Using Docker
For more details on Docker usage, see DOCKER.md.
Key Features
๐ค AI-Powered Task Management
PRD Generation (
generate_prd
): Transform project ideas into comprehensive Product Requirements DocumentsIntelligent Task Breakdown (
parse_prd
): AI-powered parsing of PRDs into actionable development tasksSmart Feature Addition (
add_feature
): Add new features with automatic impact analysis and task generationTask Complexity Analysis (
analyze_task_complexity
): Detailed AI analysis of task complexity, effort estimation, and risk assessmentNext Task Recommendations (
get_next_task
): AI-powered recommendations for optimal task prioritizationTask Expansion (
expand_task
): Break down complex tasks into manageable subtasks automaticallyPRD Enhancement (
enhance_prd
): Improve existing PRDs with AI-powered gap analysis and improvements
๐ฏ Enhanced Task Context Generation
Traceability-Based Context (Default): Rich context from requirements traceability without AI dependency
AI-Enhanced Context (Optional): Comprehensive business, technical, and implementation context using AI
Configurable Context Levels: Choose between minimal, standard, and full context depth
Business Context: Extract business objectives, user impact, and success metrics
Technical Context: Analyze technical constraints, architecture decisions, and integration points
Implementation Guidance: AI-generated step-by-step implementation recommendations
Contextual References: Links to relevant PRD sections, features, and technical specifications
Enhanced Acceptance Criteria: Detailed, testable criteria with verification methods
Graceful Degradation: Works perfectly without AI keys, falls back to traceability-based context
๐ Complete Requirements Traceability
End-to-End Tracking (
create_traceability_matrix
): Full traceability from PRD business requirements โ features โ use cases โ tasksBidirectional Links: Complete bidirectional traceability with impact analysis
Use Case Management: Professional actor-goal-scenario use case generation and tracking
Coverage Analysis: Comprehensive coverage metrics with gap identification
Orphaned Task Detection: Identify tasks without requirements links
Change Impact Analysis: Track requirement changes and their impact across all levels
๐ Multi-Provider AI Support
Anthropic Claude: Primary AI provider for complex reasoning
OpenAI GPT: Alternative provider with fallback support
Google Gemini: Additional AI capabilities
Perplexity: Research and analysis tasks
Automatic Fallback: Seamless switching between providers
๐๏ธ Core Project Management
Project Management: Create and manage GitHub Projects (v2)
Issues and Milestones: Full CRUD operations with advanced filtering
Sprint Planning: Plan and manage development sprints with AI assistance
Custom Fields and Views: Create different views (board, table, timeline, roadmap)
Resource Versioning: Intelligent caching and optimistic locking
โก Advanced Features
MCP Implementation: Full MCP specification compliance with Zod validation
GitHub Integration: GraphQL API integration with intelligent rate limiting
Real-time Sync: Bidirectional synchronization with GitHub
Webhook Integration: Real-time updates via GitHub webhooks
Progress Tracking: Comprehensive metrics and progress reporting
Event System: Track and replay project events
Installation
Option 1: Install from npm (recommended)
Option 2: Install from source
Set up environment variables
Configuration
Required Environment Variables
GitHub Configuration
The GitHub token requires these permissions:
repo
(Full repository access)project
(Project access)write:org
(Organization access)
AI Provider Configuration
At least one AI provider is required for AI-powered features:
AI Provider Setup
Anthropic Claude
Sign up at Anthropic Console
Create an API key
Set
ANTHROPIC_API_KEY
in your environment
OpenAI
Sign up at OpenAI Platform
Create an API key
Set
OPENAI_API_KEY
in your environment
Google Gemini
Sign up at Google AI Studio
Create an API key
Set
GOOGLE_API_KEY
in your environment
Perplexity
Sign up at Perplexity API
Create an API key
Set
PERPLEXITY_API_KEY
in your environment
Usage
As a command-line tool
If installed globally:
Running from source with TypeScript
If you're developing or running from source:
Command Line Options
Option | Short | Description |
|
| GitHub personal access token |
|
| GitHub repository owner (username or organization) |
|
| GitHub repository name |
|
| Path to .env file (default: .env in project root) |
|
| Enable verbose logging |
|
| Display help information |
| Display version information |
Command line arguments take precedence over environment variables.
As a Node.js module
Integration with MCP clients
For more examples, see the User Guide and the examples/ directory.
AI Tools Usage Examples
Complete Project Workflow
Feature Addition Workflow
Requirements Traceability
Enhanced Task Context Generation
Context Generation Levels:
Minimal: Basic traceability context only (fastest)
Standard: Traceability + basic business context (default)
Full: Complete AI-enhanced context with implementation guidance
Generated Task Context Includes:
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
๐งช Testing Enhanced Context Generation
The enhanced context generation functionality includes comprehensive test coverage:
Test Files Created:
src/__tests__/TaskContextGenerationService.test.ts
- Core context generation service testssrc/__tests__/TaskGenerationService.enhanced.test.ts
- Enhanced task generation integration testssrc/__tests__/ParsePRDTool.enhanced.test.ts
- Tool-level context generation tests
Test Coverage:
Traceability-based context generation (default behavior)
AI-enhanced context generation (when AI is available)
Graceful fallback when AI services are unavailable
Configuration validation and environment variable handling
Error handling and resilience testing
Integration testing with existing task generation pipeline
Running Context Generation Tests:
๐งช Comprehensive E2E Testing Suite
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.
Test Coverage:
โ 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
Quick Start:
Test Runner Options:
Environment Setup for Real API Testing:
GitHub API (Required for GitHub tools):
AI APIs (Required for AI tools):
Enable Real API Testing:
Test Features:
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
Documentation:
๐ Comprehensive E2E Testing Guide - Detailed testing documentation
๐ง Test Configuration - Jest configuration for E2E tests
๐ ๏ธ Test Utilities - Reusable test utilities
The E2E test suite ensures that all MCP tools work correctly both individually and in complex workflows, providing confidence in the reliability and integration of the entire system.
Test Scenarios Covered:
โ Default traceability-based context (no AI required)
โ AI-enhanced business context generation
โ AI-enhanced technical context generation
โ Implementation guidance generation
โ Context merging and conflict resolution
โ Error handling and graceful degradation
โ Configuration validation and defaults
โ Tool-level parameter validation
โ Integration with existing traceability system
Installing in AI Assistants
Install in Claude
To install the MCP server in Claude Desktop:
For Claude Code CLI, run:
Install in Roocode
Add this to your Roocode configuration:
Install in Windsurf
Add this to your Windsurf MCP config file:
See Windsurf MCP docs for more information.
Install in VS Code
Add this to your VS Code MCP config file:
See VS Code MCP docs for more information.
Install in Cursor
Add this to your Cursor MCP config file:
See Cursor MCP docs for more information.
Using Docker
If you prefer to run the MCP server in a Docker container:
Build the Docker Image:
Create a
Dockerfile
in your project directory: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"]Build the image:
docker build -t github-project-manager-mcp .Configure Your MCP Client:
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" } } } }
Troubleshooting
Common Issues
Module Not Found Errors
If you encounter module resolution issues, try using
bunx
instead ofnpx
:{ "mcpServers": { "github-project-manager": { "command": "bunx", "args": ["-y", "mcp-github-project-manager"] } } }Windows-Specific Configuration
On Windows, you may need to use
cmd
to run the command:{ "mcpServers": { "github-project-manager": { "command": "cmd", "args": [ "/c", "npx", "-y", "mcp-github-project-manager" ] } } }Permission Issues
If you encounter permission issues, make sure your GitHub token has the required permissions listed in the Configuration section.
Architecture
The server follows Clean Architecture principles with distinct layers:
Domain Layer: Core entities, repository interfaces, and Zod schemas
Infrastructure Layer: GitHub API integration and implementations
Service Layer: Business logic coordination
MCP Layer: Tool definitions and request handling
See ARCHITECTURE.md for detailed architecture documentation.
Contributing
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
Fork the repository
Create a feature branch:
git checkout -b feature/amazing-feature
Commit your changes:
git commit -m 'Add some amazing feature'
Push to the branch:
git push origin feature/amazing-feature
Open a Pull Request
License
This project is licensed under the MIT License - see the LICENSE file for details.
References
Current Status
Core Features
Feature | Status | Notes |
Project Creation | โ Complete | Full support for v2 projects |
Milestone Management | โ Complete | CRUD operations implemented |
Sprint Planning | โ Complete | Including metrics tracking |
Issue Management | โ Complete | With custom fields support |
Resource Versioning | โ Complete | With optimistic locking and schema validation |
Webhook Integration | ๐ Planned | Real-time updates |
AI-Powered Features
Feature | Status | Notes |
PRD Generation | โ Complete | Multi-provider AI support with comprehensive PRD creation |
Task Generation | โ Complete | AI-powered parsing of PRDs into actionable tasks |
Feature Addition | โ Complete | Smart feature addition with impact analysis |
Task Complexity Analysis | โ Complete | Detailed AI analysis with risk assessment |
Task Recommendations | โ Complete | AI-powered next task recommendations |
Task Expansion | โ Complete | Break down complex tasks into subtasks |
PRD Enhancement | โ Complete | AI-powered PRD improvement and gap analysis |
Requirements Traceability | โ Complete | End-to-end traceability matrix with coverage analysis |
Requirements Traceability
Feature | Status | Notes |
Business Requirements Extraction | โ Complete | Extract from PRD objectives and success metrics |
Use Case Generation | โ Complete | Actor-goal-scenario structure with alternatives |
Traceability Links | โ Complete | Bidirectional links with impact analysis |
Coverage Analysis | โ Complete | Gap identification and orphaned task detection |
Change Tracking | โ Complete | Requirement change impact analysis |
Verification Tracking | โ Complete | Test case mapping and verification status |
MCP Implementation
Component | Status | Notes |
Tool Definitions | โ Complete | All core tools implemented with Zod validation |
Resource Management | โ Complete | Full CRUD operations with versioning |
Security | โ Complete | Token validation and scope checking |
Error Handling | โ Complete | According to MCP specifications |
Transport | โ Complete | Stdio and HTTP support |
See STATUS.md for detailed implementation status. | Resource Management | โ Complete | With optimistic locking and relationship tracking | | Response Handling | โ Complete | Rich content formatting with multiple content types | | Error Handling | โ Complete | Comprehensive error mapping to MCP error codes | | State Management | โ Complete | With conflict resolution and rate limiting |
Recent Improvements
Enhanced Resource System:
Added Zod schema validation for all resource types
Implemented resource relationship tracking
Created a centralized ResourceFactory for consistent resource access
Improved GitHub API Integration:
Added intelligent rate limiting with automatic throttling
Implemented pagination support for REST and GraphQL APIs
Enhanced error handling with specific error types
Advanced Tool System:
Created tool definition registry with Zod validation
Implemented standardized tool response formatting
Added example-based documentation for all tools
Rich Response Formatting:
Added support for multiple content types (JSON, Markdown, HTML, Text)
Implemented progress updates for long-running operations
Added pagination support for large result sets
Identified Functional Gaps
Despite the recent improvements, the following functional gaps still exist and are prioritized for future development:
Persistent Caching Strategy:
While the ResourceCache provides in-memory caching, it lacks persistence across server restarts
No distributed caching for multi-instance deployments
Missing cache eviction policies for memory management
Real-time Event Processing:
No webhook integration for real-time updates from GitHub
Missing event-based subscription system for clients
Lack of server-sent events (SSE) support for streaming updates
Advanced GitHub Projects v2 Features:
Limited support for custom field types and validation
Incomplete integration with GitHub's newer Projects v2 field types
Missing automation rule management
Performance Optimization:
No query batching for related resources
Missing background refresh for frequently accessed resources
Incomplete prefetching for related resources
Data Visualization and Reporting:
No built-in visualization generators for metrics
Missing report generation capabilities
Limited time-series data analysis
See docs/mcp/gaps-analysis.md for detailed implementation status.
Documentation
User Guide - Detailed usage instructions
API Reference - Comprehensive tool documentation
Tutorials - Step-by-step guides
Examples - Code examples for common tasks
Architecture - System architecture and design
Contributing - Development guidelines
MCP Documentation - MCP-specific details
Interactive Documentation
For an interactive exploration of the API, open the API Explorer in your browser.
Development
Testing
Code Quality
Contributing
We welcome contributions to the GitHub Project Manager MCP Server! Please see our Contributing Guide for details on:
License
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
A comprehensive server that provides AI-powered GitHub project management with task generation from requirements and complete traceability from business requirements to implementation.
Related MCP Servers
- AsecurityAlicenseAqualityProvides comprehensive tools for managing GitHub projects, milestones, tasks, and sprints. This server integrates deeply with GitHub Projects V2, offering features like automated kanban workflows, sprint planning, and custom field management.Last updated -461070MIT License
- AsecurityAlicenseAqualityEnables users to interact with GitHub's Projects v2 API through natural language for Agile project management, supporting repository details, issue tracking, and project board management operations.Last updated -30GPL 2.0
- AsecurityFlicenseAqualityEnables comprehensive GitHub operations through natural language including file management, repository administration, issue tracking, and advanced code searching.Last updated -4711
- -securityFlicense-qualityA set of tools allowing AI assistants to interact directly with GitHub, enabling automation of tasks like fetching user profiles, creating repositories, and managing pull requests.Last updated -