GitHub Project Manager

by kunwarvivek

17 stars
1 downloads
Not rated
GitHub

About

Provides 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.

Details

Author
kunwarvivek
Repository
kunwarVivek/mcp-github-project-manager
GitHub stars
17
Downloads
1
License
MIT License
Categories
Productivity, Developer Tools, Design, Workplace, AI, Communication, Security, Project Management

Jump to

- 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

// Add new feature with complete lifecycle
{"tool": "ai_generate", "arguments": {"action": "add_feature", "featureIdea": "Advanced Analytics Dashboard", "description": "Real-time analytics with AI insights", "expandToTasks": true}}
// Automatically creates: business requirements, use cases, tasks with traceability, lifecycle tracking

// Create traceability matrix

{"tool": "ai_generate", "arguments": {"action": "create_traceability_matrix", "projectId": "task-ai-pro", "validateCompleteness": true}}

- 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

| 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 | ✅ Complete | Real-time updates; fail-closed HMAC signature validation + SSE streaming |

| 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 |

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

  1. Download and install Highlight from highlightai.com/download
  2. Navigate to the plugins tab and select "Add Custom Plugin"
  3. Configure the plugin with the settings below
    Plugin Name GitHub Project Manager
    Command (node, npx, python, etc.) npx
    Arguments
    • Argument 1 -y
    • Argument 2 mcp-github-project-manager
    Environment
    • GITHUB_REPO your_repo
    • GITHUB_OWNER your_username
    • GITHUB_TOKEN your_github_token
    • AI_MAIN_MODEL deepseek/deepseek-chat
    • AI_MAIN_API_KEY sk-or-v1-your-key
    • AI_MAIN_BASE_URL https://openrouter.ai/api/v1
    • AI_MAIN_PROVIDER openai-compatible

    Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.

  4. Enable "Start Automatically" if you want the plugin to start when Highlight launches

From the repository

- Deployment Guide - Installation, Docker, and MCP client setup
- Configuration Guide - All configuration options
- Troubleshooting Guide - Common issues and solutions

npm install -g mcp-github-project-manager

export GITHUB_TOKEN="your_github_token"
export GITHUB_OWNER="your_github_username_or_organization"
export GITHUB_REPO="your_repository_name"

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
bash

npm install mcp-github-project-manager
bash

npm install


cp .env.example .env
env
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)


AI keys are optional — without them, non-AI tools (project management, issues, sprints, agents) work fine. AI-powered features (ai_generate, ai_analyze, ai_plan) need at least one key.
env

AI_MAIN_MODEL=claude-sonnet-4-20250514 # general tasks
AI_PRD_MODEL=claude-opus-5 # PRD generation
AI_RESEARCH_MODEL=sonar-pro # research
AI_FALLBACK_MODEL=gpt-4o-mini # fallback



Each model role can independently use a different provider, API key, and endpoint.

Use openai-compatible for OpenRouter, Together, Groq, Ollama, or any OpenAI-protocol endpoint:
env

GITHUB_TOKEN=your_token mcp-github-project-manager

If you're developing or running from source:
json // 1. Create a project {"tool": "manage_project", "arguments": {"action": "create", "title": "My Project", "owner": "myorg"}}

// 2. Create an issue
{"tool": "manage_issues", "arguments": {"action": "create", "title": "First Issue", "body": "Description here"}}

// 3. Register an AI agent
{"tool": "agent_work", "arguments": {"action": "register", "name": "claude-eng-1", "role": "engineer"}}

// 4. Agent checks out a task
{"tool": "agent_work", "arguments": {"action": "checkout_task", "agentId": "agent-abc123", "strategy": "highest_priority"}}

// 5. Discover available tools at runtime
{"tool": "discover_tools", "arguments": {}}
{"tool": "discover_tools", "arguments": {"group": "manage_issues", "action": "create", "includeSchemas": true}}



Control which compound tools are exposed to MCP clients:
bash
bash

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):



To install the MCP server in Claude Desktop:
json
{
"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",
"AI_MAIN_PROVIDER": "openai-compatible",
"AI_MAIN_BASE_URL": "https://openrouter.ai/api/v1",
"AI_MAIN_API_KEY": "sk-or-v1-your-key",
"AI_MAIN_MODEL": "deepseek/deepseek-chat"
}
}
}
}


Or with a direct provider key (simpler):
json
{
"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"
}
}
}
}


For Claude Code CLI, run:
bash
claude mcp add github-project-manager -- npx -y mcp-github-project-manager


Add this to your Roocode configuration:
json
{
"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:
json
{
"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:
json
{
"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:
json
{
"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.
json
// 1. Register the agent
{"tool": "agent_work", "arguments": {"action": "register", "name": "claude-eng-1", "role": "engineer", "runtime": "claude-code", "capabilities": ["typescript", "react", "testing"]}}
// → { id: "agent-abc123", status: "idle", ... }

// 2. Check out a task
{"tool": "agent_work", "arguments": {"action": "checkout_task", "agentId": "agent-abc123", "strategy": "highest_priority"}}
// → { success: true, issueNumber: 42, issueTitle: "Add login form", branchSuggestion: "feat/42-add-login-form" }

// 3. Get full context
{"tool": "agent_work", "arguments": {"action": "get_task_context", "issueNumber": 42}}
// → { issue: {...}, milestone: {...}, acceptanceCriteria: [...], codingStandards: "..." }

// 4. Work on the task, sending heartbeats periodically
{"tool": "agent_work", "arguments": {"action": "heartbeat", "agentId": "agent-abc123", "status": "working", "taskId": "issue-42", "progress": 60, "progressSummary": "Tests passing, working on edge cases", "currentBranch": "feat/42-add-login-form"}}

// 5. Submit the work product
{"tool": "agent_manage", "arguments": {"action": "submit_work_product", "agentId": "agent-abc123", "taskId": "issue-42", "issueNumber": 42, "branch": "feat/42-add-login-form", "prNumber": 99, "summary": "Added login form with email/password validation"}}

// 6. Complete the task
{"tool": "agent_work", "arguments": {"action": "complete_task", "agentId": "agent-abc123", "taskId": "issue-42", "summary": "Implemented login form with validation and tests"}}

// 7. Repeat: checkout next task
{"tool": "agent_work", "arguments": {"action": "checkout_task", "agentId": "agent-abc123", "strategy": "highest_priority"}}
```

generate_prd

Transform project ideas into comprehensive Product Requirements Documents.

parse_prd

AI-powered parsing of PRDs into actionable development tasks.

add_feature

Add new features with automatic impact analysis and task generation.

analyze_task_complexity

Detailed AI analysis of task complexity, effort estimation, and risk assessment.

get_next_task

AI-powered recommendations for optimal task prioritization.

expand_task

Break down complex tasks into manageable subtasks automatically.

enhance_prd

Improve existing PRDs with AI-powered gap analysis and improvements.

materialize_tasks

Convert generated tasks into real GitHub issues grouped into milestones and sprints with dependency-driven phase ordering.

create_traceability_matrix

Full traceability from PRD business requirements to features, use cases, and tasks.

register

Register an AI agent with role, runtime, and capabilities.

checkout_task

Claim the next available task using a selection strategy.

complete_task

Mark a task as completed with a summary.

heartbeat

Report liveness, progress percentage, branch, and blockers.

submit_work_product

Submit code changes with branch, PR, files, and test results.

set_budget

Configure token budget, warning threshold, hard stop, and reset period.

get_budget

Check an agent's token budget (used, remaining, warnings).

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "github project manager": {
            "env": {
                "GITHUB_REPO": "your_repo",
                "GITHUB_OWNER": "your_username",
                "GITHUB_TOKEN": "your_github_token",
                "AI_MAIN_MODEL": "deepseek/deepseek-chat",
                "AI_MAIN_API_KEY": "sk-or-v1-your-key",
                "AI_MAIN_BASE_URL": "https://openrouter.ai/api/v1",
                "AI_MAIN_PROVIDER": "openai-compatible"
            },
            "args": [
                "-y",
                "mcp-github-project-manager"
            ],
            "command": "npx"
        }
    }
}

Linux

{
    "env": {
        "GITHUB_REPO": "your_repo",
        "GITHUB_OWNER": "your_username",
        "GITHUB_TOKEN": "your_github_token",
        "AI_MAIN_MODEL": "deepseek/deepseek-chat",
        "AI_MAIN_API_KEY": "sk-or-v1-your-key",
        "AI_MAIN_BASE_URL": "https://openrouter.ai/api/v1",
        "AI_MAIN_PROVIDER": "openai-compatible"
    },
    "args": [
        "-y",
        "mcp-github-project-manager"
    ],
    "command": "npx"
}

Macos

{
    "env": {
        "GITHUB_REPO": "your_repo",
        "GITHUB_OWNER": "your_username",
        "GITHUB_TOKEN": "your_github_token",
        "AI_MAIN_MODEL": "deepseek/deepseek-chat",
        "AI_MAIN_API_KEY": "sk-or-v1-your-key",
        "AI_MAIN_BASE_URL": "https://openrouter.ai/api/v1",
        "AI_MAIN_PROVIDER": "openai-compatible"
    },
    "args": [
        "-y",
        "mcp-github-project-manager"
    ],
    "command": "npx"
}

Windows

{
    "env": {
        "GITHUB_REPO": "your_repo",
        "GITHUB_OWNER": "your_username",
        "GITHUB_TOKEN": "your_github_token",
        "AI_MAIN_MODEL": "deepseek/deepseek-chat",
        "AI_MAIN_API_KEY": "sk-or-v1-your-key",
        "AI_MAIN_BASE_URL": "https://openrouter.ai/api/v1",
        "AI_MAIN_PROVIDER": "openai-compatible"
    },
    "args": [
        "/c",
        "npx",
        "-y",
        "mcp-github-project-manager"
    ],
    "command": "cmd"
}

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 a full end-to-end pipeline from project ideas to GitHub issues, sprints, and milestones.

npm version
License: MIT
Node.js Version

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

- 16 Compound Tools (152 actions): Progressive-disclosure API — AI agents see 16 tools instead of 131, with discover_tools for runtime exploration
- AI-Powered: Transform project ideas into comprehensive PRDs and actionable tasks using multiple AI providers
- Agent Orchestration: Autonomous AI agent task assignment, heartbeat monitoring, budget enforcement, and work product tracking
- PRD-to-Issues Pipeline: Materialize AI-generated tasks into GitHub milestones, sprints, and issues with dependency-driven sequencing
- 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

- Overview
- Quick Start
- Key Features
- Installation
- Configuration
- Usage
- As a command-line tool
- Running from source with TypeScript
- As a Node.js module
- Integration with MCP clients
- Installing in AI Assistants
- Claude
- Roocode
- Windsurf
- VS Code
- Cursor
- Using Docker
- Troubleshooting
- Agent Orchestration
- Architecture
- Contributing
- License
- References
- Current Status

Quick Start

Using NPM

```bash
No reviews yet — be the first

Sign in to leave a review

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

Install

Add to Claude Desktop or Cursor

{
    "mcpServers": {
        "github project manager": {
            "env": {
                "GITHUB_REPO": "your_repo",
                "GITHUB_OWNER": "your_username",
                "GITHUB_TOKEN": "your_github_token",
                "AI_MAIN_MODEL": "deepseek/deepseek-chat",
                "AI_MAIN_API_KEY": "sk-or-v1-your-key",
                "AI_MAIN_BASE_URL": "https://openrouter.ai/api/v1",
                "AI_MAIN_PROVIDER": "openai-compatible"
            },
            "args": [
                "-y",
                "mcp-github-project-manager"
            ],
            "command": "npx"
        }
    }
}

More like this

Similar MCP servers you might find useful

Browse category

Time

A Model Context Protocol server that provides time and timezone conversion capabilities. It enables LLMs to get current time information and perform timezone…

88.2k
Productivity

Git

A Model Context Protocol (MCP) server that provides tools for LLMs to read, search, and manipulate Git repositories. It enables automated repository…

88.1k
Developer Tools

Context 7

Official Context7 MCP server that brings up-to-date, version-specific library documentation and code examples into AI coding prompts.

58.7k
Developer Tools