接入你的智能体
从发布者处安装。不是 PlugMCP 端点。
远程 URL 还是本机命令？ 两种安装方式的区别
来自发布者
The agentic task substrate for AI coding agents. An MCP server that turns GitHub Projects v2 into a fully autonomous project management platform — AI agents self-assign work, track progress, review each other, and ship code, all backed by GitHub-native storage.
Use case: You have AI agents (Claude Code, Codex, Cursor, Windsurf, Roo). They need a task backbone. This is it.
MCP server for AI-powered GitHub project management — 20 tools, 169 actions, agent swarm orchestration, GitHub Actions/Releases/Branches, MCP Resources & Prompts, PRD-to-issues pipeline
This MCP server implements the Model Context Protocol to provide a complete agentic project management layer over GitHub Projects v2. AI agents register, self-assign tasks, coordinate via heartbeats, submit work products for review, and operate within token budgets — all through 20 compound tools exposing 169 actions. Human project managers get AI-powered PRD generation, sprint planning, issue triage, and roadmap creation. Everything is backed by GitHub-native storage (issues, project fields, comments) — no external infrastructure required.
AI coding agents are powerful but stateless — they don't know what to work on next, can't coordinate with other agents, and have no persistent task memory. This MCP server solves that by turning GitHub Projects into an agentic operating layer:
Beyond tools, this server implements the full MCP v2 capability surface:
discover_tools# 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
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 improvementsmaterialize_tasks): Convert generated tasks into real GitHub issues grouped into milestones and sprints with dependency-driven phase orderingcreate_traceability_matrix): Full traceability from PRD business requirements → features → use cases → tasksaction routing replace 169 individual actions — simpler for AI agentsdiscover_tools meta-tool for exploring available actions and schemassmart_assign)converge_project)# 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 or pnpm - use whichever you have)
pnpm install
# Build the project
pnpm 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)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.
# Global AI provider keys (set the ones you have)
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 (no defaults — configure what you want to use)
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:
# OpenRouter for cheap daily tasks
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
# Direct Anthropic for PRD generation
AI_PRD_PROVIDER=anthropic
AI_PRD_API_KEY=sk-ant-your-key
AI_PRD_MODEL=claude-opus-5
# Local Ollama as fallback
AI_FALLBACK_PROVIDER=openai-compatible
AI_FALLBACK_BASE_URL=http://localhost:11434/v1
AI_FALLBACK_API_KEY=ollama
AI_FALLBACK_MODEL=llama3.1
See the Configuration Guide for full per-role documentation.
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:
# Use the npm dev script (watches for changes) — recommended
pnpm run dev
# Run directly with tsx
pnpm exec tsx src/index.ts
# Run with command line arguments
pnpm exec tsx src/index.ts --token=your_token --owner=your_username --repo=your_repo
# Display help information
pnpm exec tsx src/index.ts --help
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 (compound API)
const result = await client.callTool("manage_project", {
action: "create",
title: "My Project",
owner: "myorg"
});
For more examples, see the User Guide and the examples/ directory.
The MCP server exposes 20 compound tools (169 actions). Each tool accepts an action parameter that routes to the underlying operation. Use discover_tools to explore capabilities at runtime.
// 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}}
// 1. Generate PRD from project idea
{"tool": "ai_generate", "arguments": {"action": "generate_prd", "projectIdea": "AI-powered task management with real-time collaboration", "projectName": "TaskAI Pro", "complexity": "high"}}
// 2. Parse PRD into tasks with traceability
{"tool": "ai_generate", "arguments": {"action": "parse_prd", "prdContent": "<generated PRD>", "maxTasks": 30, "createTraceabilityMatrix": true}}
// 3. Get next task recommendations
{"tool": "ai_generate", "arguments": {"action": "get_next_task", "sprintCapacity": 40, "teamSkills": ["react", "node.js", "typescript"]}}
// 4. Analyze task complexity
{"tool": "ai_generate", "arguments": {"action": "analyze_complexity", "taskTitle": "Implement real-time collaboration", "includeRisks": true}}
// 5. Break down complex tasks
{"tool": "ai_generate", "arguments": {"action": "expand_task", "taskTitle": "Build analytics dashboard", "currentComplexity": 8, "targetComplexity": 3}}
// 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}}
// List all compound tools
{"tool": "discover_tools", "arguments": {}}
// Explore a specific tool's actions
{"tool": "discover_tools", "arguments": {"group": "ai_generate"}}
// Get full schema for a specific action
{"tool": "discover_tools", "arguments": {"group": "ai_generate", "action": "generate_prd", "includeSchemas": true}}
Control which compound tools are exposed to MCP clients:
# Default: all tools exposed
MCP_TOOL_GROUPS=all
# Expose only project management tools
MCP_TOOL_GROUPS=core
# Add AI tools
MCP_TOOL_GROUPS=core,ai
discover_tools is always available regardless of this setting.
Context Generation Levels:
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)
pnpm run test:ai
# Run specific context generation tests
pnpm test TaskContextGeneration
pnpm test enhanced
# Run all tests
pnpm 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)
pnpm run test:e2e:tools
# Run with real APIs (requires credentials)
pnpm run test:e2e:tools:real
# Use the interactive test runner
pnpm run test:e2e:runner
# Run specific test categories
pnpm run test:e2e:tools:github # GitHub tools only
pnpm run test:e2e:tools:ai # AI tools only
pnpm 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 pnpm 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",
"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):
{
"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:
claude mcp add github-project-manager -- pnpm dlx 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:
docker build -t mcp-gh-project .
docker run -d \
-e GITHUB_TOKEN=your_github_token \
-e GITHUB_OWNER=your_github_owner \
-e GITHUB_REPO=your_repository_name \
mcp-gh-project:latest
Or with CLI arguments:
docker run -d mcp-gh-project:latest \
--github_token your_github_token \
--github_owner your_owner \
--github_repo your_repo
{
"mcpServers": {
"github-project-manager": {
"command": "docker",
"args": ["run", "-i", "--rm", "-e", "GITHUB_TOKEN", "-e", "GITHUB_OWNER", "-e", "GITHUB_REPO", "mcp-gh-project:latest"],
"env": {
"GITHUB_TOKEN": "your_token",
"GITHUB_OWNER": "your_owner",
"GITHUB_REPO": "your_repo"
}
}
}
}
"env": {
"GITHUB_TOKEN": "your_github_token",
"GITHUB_OWNER": "your_username",
"GITHUB_REPO": "your_repo"
}
}
}
}
### Troubleshooting
#### Common Issues
1. **Module Not Found Errors**
If you encounter module resolution issues, try using `bunx` instead of `npx`:
```json
{
"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 agent orchestration layer enables autonomous AI agents (Claude Code, Codex, Cursor, etc.) to self-assign tasks, report progress, submit work products, and operate within token budgets — all backed by GitHub-native storage.
Agents interact with the orchestration layer through two compound tools — agent_work (task lifecycle) and agent_manage (administration):
┌─────────────────────────────────────────────────────────────────────┐
│ Agent Orchestration Layer │
│ │
│ ┌───────────┐ ┌──────────────┐ ┌─────────────┐ ┌────────────┐ │
│ │ Agent │ │ Task │ │ Work │ │ Budget │ │
│ │ Registry │ │ Checkout │ │ Products │ │ Manager │ │
│ └───────────┘ └──────────────┘ └─────────────┘ └────────────┘ │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ GitHub-Native Storage (Issues + Projects) │ │
│ │ • Agent registry → pinned issue (label: agent-registry) │ │
│ │ • Task claims → project custom fields │ │
│ │ • Work products → structured issue comments │ │
│ │ • Budgets → agent registry metadata │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
// 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"}}
Agents can register child agents using parentAgentId. This enables multi-agent architectures:
// Parent agent registers itself
{"tool": "agent_work", "arguments": {"action": "register", "name": "lead-agent", "role": "pm", "runtime": "claude-code"}}
// → { id: "agent-lead" }
// Parent spawns a sub-agent
{"tool": "agent_work", "arguments": {"action": "register", "name": "worker-1", "role": "engineer", "runtime": "claude-code", "parentAgentId": "agent-lead", "capabilities": ["typescript", "testing"]}}
// Deregistering the parent cascades to all children
{"tool": "agent_manage", "arguments": {"action": "deregister", "agentId": "agent-lead"}}
// → Removes lead-agent and worker-1
Token budgets prevent runaway AI costs:
// Set a daily budget with 80% warning
{"tool": "agent_manage", "arguments": {"action": "set_budget", "agentId": "agent-abc123", "totalTokens": 500000, "warningThreshold": 0.8, "hardStop": true, "resetPeriod": "daily"}}
// Check budget status before expensive operations
{"tool": "agent_manage", "arguments": {"action": "get_budget", "agentId": "agent-abc123"}}
// → { usedTokens: 350000, remainingTokens: 150000, usagePercent: 70, isWarning: false, isExhausted: false }
All orchestration state lives in your GitHub repository — no external database required:
See the Tool Reference for detailed parameter documentation.
The server follows Clean Architecture principles with distinct layers:
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
git checkout -b feature/amazing-featuregit commit -m 'Add some amazing feature'git push origin feature/amazing-featureThis project is licensed under the MIT License - see the LICENSE file for details.
See .planning/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 |
Dependency & SDK modernization (2026-07-15):
@octokit/rest 22Architecture & reliability (2026-07-15):
ProjectManagementService facade (extracted IssueService, RoadmapService; automation delegates to ProjectAutomationService)SECRETS_DIR) with rotationMAX_CACHE_ENTRIES) and a namespace-index cleanup fixEnhanced Resource System:
Improved GitHub API Integration:
Advanced Tool System:
Rich Response Formatting:
Remaining gaps prioritized for future development (updated 2026-07-15). The live,
code-verified status is in docs/remediation/GAP-TRACKER.md.
Distributed Caching:
CachePersistence) and size-bounded
oldest-first eviction (MAX_CACHE_ENTRIES). Still single-instance only —
no distributed/shared cache for multi-instance deployments.Performance Optimization:
Data Visualization and Reporting (roadmap phase 11, not yet built):
Resolved since earlier snapshots: real-time webhook integration + SSE streaming, automation-rule management, cache persistence + eviction, and a fail-closed webhook signature check.
For an interactive exploration of the API, open the API Explorer in your browser.
# Unit tests
pnpm test
# AI service/tool tests
pnpm run test:ai
# End-to-end tests
pnpm run test:e2e
# E2E MCP tool suite (mocked GitHub/AI)
pnpm run test:e2e:tools
# Lint code
pnpm run lint
# Type check
pnpm exec tsc --noEmit
# Format code
pnpm run format
We welcome contributions to the GitHub Project Manager MCP Server! Please see our Contributing Guide for details on:
MCP server for AI-powered GitHub project management — 20 tools, 169 actions, agent swarm orchestration, GitHub Actions/Releases/Branches, MCP Resources & Prompts, PRD-to-issues pipeline
工具
暂无工具列表。远程服务器在首次健康检查后会获得工具列表。
常见问题
在本页复制适用于 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 配置。它使用发布者的安装方式，而不是 PlugMCP 代理。
此记录未列出必需的环境变量。
MCP Github Project Manager 通过 stdio 在本地运行。
上次检查时间：2026-10-28。 MCP server for AI-powered GitHub project management — 20 tools, 169 actions, agent swarm orchestration, GitHub Actions/Releases/Branches, MCP Resources & Prompts, PRD-to-issues pipeline
