
Research
Security News
The Growing Risk of Malicious Browser Extensions
Socket researchers uncover how browser extensions in trusted stores are used to hijack sessions, redirect traffic, and manipulate user behavior.
mcp-github-project-manager
Advanced tools
A Model Context Protocol (MCP) server for managing GitHub Projects
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.
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.
# Install the package globally
npm install -g mcp-github-project-manager
# Set up your environment variables
export GITHUB_TOKEN="your_github_token"
export GITHUB_OWNER="your_github_username_or_organization"
export GITHUB_REPO="your_repository_name"
# Run the MCP server
mcp-github-project-manager
# Build the Docker image
docker build -t mcp-github-project-manager .
# Run with environment variables
docker run -it \
-e GITHUB_TOKEN=your_github_token \
-e GITHUB_OWNER=your_github_username_or_organization \
-e GITHUB_REPO=your_repository_name \
mcp-github-project-manager
For more details on Docker usage, see DOCKER.md.
generate_prd
): Transform project ideas into comprehensive Product Requirements Documentsparse_prd
): AI-powered parsing of PRDs into actionable development tasksadd_feature
): Add new features with automatic impact analysis and task generationanalyze_task_complexity
): Detailed AI analysis of task complexity, effort estimation, and risk assessmentget_next_task
): AI-powered recommendations for optimal task prioritizationexpand_task
): Break down complex tasks into manageable subtasks automaticallyenhance_prd
): Improve existing PRDs with AI-powered gap analysis and improvementscreate_traceability_matrix
): Full traceability from PRD business requirements โ features โ use cases โ tasks# 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
ANTHROPIC_API_KEY
in your environmentOPENAI_API_KEY
in your environmentGOOGLE_API_KEY
in your environmentPERPLEXITY_API_KEY
in your environmentIf installed globally:
# 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
If you're developing or running from source:
# 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
Option | Short | Description |
---|---|---|
--token <token> | -t | GitHub personal access token |
--owner <owner> | -o | GitHub repository owner (username or organization) |
--repo <repo> | -r | GitHub repository name |
--env-file <path> | -e | Path to .env file (default: .env in project root) |
--verbose | -v | Enable verbose logging |
--help | -h | Display help information |
--version | Display version information |
Command line arguments take precedence over environment variables.
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 the User Guide and the examples/ 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
})
Context Generation Levels:
Generated Task Context Includes:
The enhanced context generation functionality includes comprehensive test coverage:
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# 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.
# 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 API (Required for GitHub tools):
GITHUB_TOKEN=ghp_your_github_token
GITHUB_OWNER=your-github-username
GITHUB_REPO=your-test-repository
AI APIs (Required for AI tools):
# 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
Enable Real API Testing:
E2E_REAL_API=true npm run test:e2e:tools:real
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.
To install the MCP server in Claude Desktop:
{
"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"
}
}
}
}
For Claude Code CLI, run:
claude mcp add github-project-manager -- npx -y mcp-github-project-manager
Add this to your Roocode configuration:
{
"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"
}
}
}
}
See Windsurf MCP docs for more information.
Add this to your VS Code MCP config file:
{
"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"
}
}
}
}
See VS Code MCP docs for more information.
Add this to your Cursor 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"
}
}
}
}
See Cursor MCP docs for more information.
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"
}
}
}
}
Module Not Found Errors
If you encounter module resolution issues, try using bunx
instead of npx
:
{
"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.
The server follows Clean Architecture principles with distinct layers:
See ARCHITECTURE.md for detailed architecture documentation.
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
git checkout -b feature/amazing-feature
git commit -m 'Add some amazing feature'
git push origin feature/amazing-feature
This project is licensed under the MIT License - see the LICENSE file for details.
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 |
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 |
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 |
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 |
Enhanced Resource System:
Improved GitHub API Integration:
Advanced Tool System:
Rich Response Formatting:
Despite the recent improvements, the following functional gaps still exist and are prioritized for future development:
Persistent Caching Strategy:
Real-time Event Processing:
Advanced GitHub Projects v2 Features:
Performance Optimization:
Data Visualization and Reporting:
See docs/mcp/gaps-analysis.md for detailed implementation status.
For an interactive exploration of the API, open the API Explorer in your browser.
# Unit tests
npm test
# Integration tests
npm run test:integration
# End-to-end tests
npm run test:e2e
# Lint code
npm run lint
# Type check
npm run type-check
# Format code
npm run format
We welcome contributions to the GitHub Project Manager MCP Server! Please see our Contributing Guide for details on:
FAQs
A Model Context Protocol (MCP) server for managing GitHub Projects
The npm package mcp-github-project-manager receives a total of 108 weekly downloads. As such, mcp-github-project-manager popularity was classified as not popular.
We found that mcp-github-project-manager demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago.ย It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket researchers uncover how browser extensions in trusted stores are used to hijack sessions, redirect traffic, and manipulate user behavior.
Research
Security News
An in-depth analysis of credential stealers, crypto drainers, cryptojackers, and clipboard hijackers abusing open source package registries to compromise Web3 development environments.
Security News
pnpm 10.12.1 introduces a global virtual store for faster installs and new options for managing dependencies with version catalogs.