English | 한국어
MCP Project Manager
Claude Code와 통합된 종합 프로젝트 관리 및 워크플로우 추적 시스템. Model Context Protocol(MCP)을 기반으로 Claude Code 세션, 도구 사용, 에이전트 실행, 프로젝트 작업을 자동으로 캡처하여 중앙 집중식 대시보드와 데이터베이스에 저장합니다.
     
Fork 정보: 이 프로젝트는 croffasia/mcp-project-manager를 포크하여 3-tier 아키텍처로 확장한 버전입니다.
목차
개요
MCP Project Manager는 Claude Code 워크플로우를 실행 가능한 인사이트로 변환하는 3-tier 시스템입니다. 다음을 자동으로 추적합니다:
- 세션 활동 및 타임라인
- 도구 사용 패턴 및 성능
- 에이전트 실행 및 스킬 호출
- 프로젝트 작업, 마일스톤, 산출물
- 파일 변경 및 코드 메트릭
- 팀 분석 및 인사이트
시각적 대시보드, REST API를 제공하며 MCP를 통해 Claude Desktop과 원활하게 통합됩니다.
핵심 기능
- 자동 이벤트 캡처: 8개의 Claude Code 훅 핸들러가 사용자 개입 없이 세션, 도구, 에이전트, 프롬프트를 자동 캡처
- 실시간 대시보드: WebSocket을 통한 라이브 업데이트, 칸반 보드, 플로우 그래프, 분석 차트
- 플로우 시각화: 에이전트 실행, 도구 호출, 의사결정 플로우의 그래프 기반 뷰
- 스마트 분석: 토큰 사용량, 에이전트 분포, 성공률, 타임라인 인사이트
- 프로젝트 관리: 프로젝트 생성, 작업 추적, 마일스톤 설정, 산출물 관리
- 원커맨드 설치:
npx create-mcp-pm이 클론, 빌드, 설정, MCP 등록을 자동 처리
주요 기능
33개의 MCP 도구
플로우 및 세션 추적 (12개)
flow_session_start/flow_session_end- 세션 생명주기 관리flow_task_start/flow_task_end- 작업 실행 추적flow_skill_call- 스킬 호출 기록flow_error- 오류 이벤트 로깅flow_agent_spawn/flow_agent_complete- 에이전트 생명주기flow_tool_call- 도구 실행 기록flow_file_change- 파일 변경 추적flow_commit- Git 커밋 기록flow_prompt- 사용자 프롬프트 로깅
프로젝트 관리 CRUD (15개)
- 프로젝트:
pm_project_create,pm_project_update,pm_project_delete,pm_project_list,pm_project_get - 작업:
pm_task_create,pm_task_update,pm_task_delete,pm_task_list,pm_task_get - 마일스톤:
pm_milestone_create,pm_milestone_update,pm_milestone_list - 작업 관리:
pm_task_move,pm_task_assign_priority
쿼리 및 분석 (6개)
pm_dashboard_summary- KPI 요약 및 프로젝트 통계pm_timeline- 이벤트 타임라인 조회pm_flow_graph- 플로우 그래프 데이터pm_analyze_bottleneck- 병목 현상 분석pm_suggest_next_task- 다음 작업 제안pm_report_generate- 프로젝트 리포트 생성
자체 업데이트 (1개)
pm_self_update- 설치된 MCP 서버를 최신 버전으로 자동 업데이트
8개의 Claude Code 훅 핸들러
Claude Code 훅을 통한 자동 이벤트 캡처:
| 훅 | 이벤트 | 캡처 내용 | |------|-------|----------| | session-start | SessionStart | 새 세션 초기화 | | session-end | SessionEnd | 세션 완료 및 요약 | | pre-tool-use | PreToolUse | 도구 실행 전 | | post-tool-use | PostToolUse | 도구 완료, 파일 변경 | | subagent-start | SubagentStart | 에이전트 생성 | | subagent-stop | SubagentStop | 에이전트 완료 | | user-prompt-submit | UserPromptSubmit | 사용자 프롬프트 및 쿼리 | | stop | Stop | 우아한 종료 |
대시보드 기능
핵심 뷰
- 개요 페이지 (
/): KPI 카드, 프로젝트 통계, 트렌드 차트 (recharts) - 프로젝트 페이지 (
/projects): 프로젝트 목록 및 진행 상황 - 프로젝트 상세 (
/projects/[id]): - 7단계 칸반 보드 (할 일/설계/구현/리뷰/테스트/완료/보관)
- 드래그 앤 드롭 작업 관리 (@dnd-kit)
- 작업 카드 액션: 편집, 삭제, 실행 시작/중지
- 작업 실행 추적 (WebSocket 실시간 업데이트)
- 타임라인 (
/projects/[id]/timeline): 이벤트 시간순 조회 - 플로우 그래프 (
/projects/[id]/flow): 에이전트 실행 트리 시각화 (@xyflow/react v12) - 활동 페이지 (
/activities): 이벤트 목록 및 필터링 - 분석 페이지 (
/analytics): 작업 완료율, 토큰 사용량, 에이전트 분포, 세션 활동 - 설정 페이지 (
/settings): 서비스 상태, 데이터베이스 정보
실시간 업데이트
- WebSocket 기반 라이브 업데이트 (폴링 없음)
- 칸반 보드의 낙관적 업데이트
- 실시간 세션 추적
세션 및 작업 실행
- 세션 생성 및 관리
- 작업 실행 시작/중지
- 작업 단계 추적 (설계/구현/리뷰/테스트)
- 실행 상태 실시간 모니터링
아키텍처
3-Tier 설계
┌─────────────────────────────────────────┐
│ Claude Desktop / Claude Code │
│ (MCP Client) │
└──────────────┬──────────────────────────┘
│
│ MCP Protocol
▼
┌─────────────────────────────────────────┐
│ MCP Server (TypeScript) │
│ 33 Tools + 8 Hook Handlers │
│ • Flow Events & Sessions │
│ • Project Management CRUD │
│ • Analytics & Queries │
└──────────────┬──────────────────────────┘
│
│ REST API / WebSocket
▼
┌─────────────────────────────────────────┐
│ FastAPI Backend (Python 3.14) │
│ SQLAlchemy ORM + SQLite (WAL) │
│ • 15 database tables │
│ • Real-time WebSocket updates │
│ • Async/await execution │
└──────────────┬──────────────────────────┘
│
│ WebSocket / HTTP
▼
┌─────────────────────────────────────────┐
│ Next.js Dashboard (React 19) │
│ • Kanban board with drag-and-drop │
│ • Flow graph visualization │
│ • Analytics & timeline views │
│ • Real-time project tracking │
└─────────────────────────────────────────┘패키지 구조
packages/
├── mcp-server/ # TypeScript MCP Server (tsup build)
│ └── src/tools/ # 33 MCP tools
│ ├── flow-events.ts, flow-session.ts, flow-agent.ts, flow-tracking.ts
│ ├── pm-project.ts, pm-task.ts, pm-milestone.ts, pm-actions.ts
│ ├── pm-query.ts, pm-analysis.ts, pm-session.ts, pm-update.ts
│ └── index.ts
├── backend/ # FastAPI (Python 3.14) REST API + WebSocket
│ └── app/routes/ # projects, tasks, sessions, milestones, events, analytics, ws, seed, ai, labels
├── dashboard/ # Next.js 15 (App Router) Web Dashboard
│ └── src/app/ # pages: /, activities, analytics, projects, projects/[id] (kanban/timeline/flow), settings
├── cli/ # CLI tools
└── create-mcp-pm/ # Project scaffolding데이터베이스: SQLite (WAL mode) at ~/.mcp-pm/mcp_pm.db, 15 tables 포트: Backend 48293, Dashboard 48294
빠른 시작
설치
가장 빠른 시작 방법:
# 옵션 1: GitHub에서 직접 설치 (npm 계정 불필요)
curl -fsSL https://raw.githubusercontent.com/skdkfk8758/MCP-ProjectManager/main/scripts/install.sh | bash
# 옵션 2: npx (npm publish 후 사용 가능)
npx create-mcp-pm이 단일 명령이 다음을 수행합니다:
- 필수 의존성 확인 (Node.js 20+, Python 3.14+, git)
- MCP ProjectManager 저장소 클론
- pnpm을 통한 모든 의존성 설치
- 모든 패키지 빌드 (MCP Server, CLI, Dashboard, Backend)
- Python 백엔드 가상 환경 설정
- Claude Desktop에 MCP 서버 등록
- Claude Code 훅 핸들러 설치
수동 설정 (개발용)
로컬 개발 시:
# 저장소 클론
git clone https://github.com/skdkfk8758/MCP-ProjectManager.git
cd MCP_ProjectManager
# 의존성 설치
pnpm install
# 모든 패키지 빌드
pnpm build
# Python 백엔드 설정
cd packages/backend
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e .
cd ../..
# Claude Desktop 등록 및 훅 설치
mcp-pm setup
# 서비스 시작
mcp-pm start대시보드 접속
실행 후:
- 대시보드: http://localhost:48294
- 백엔드 API: http://localhost:48293
- API 문서: http://localhost:48293/docs
데모 데이터
데모 데이터를 시드하여 모든 대시보드 기능을 즉시 확인:
# 데모 데이터 시드 (3 프로젝트, 26 작업, 분석 데이터, 에이전트 통계)
bash scripts/seed-demo.sh
# 모든 데이터 초기화
bash scripts/seed-demo.sh reset
# 또는 API 직접 호출
curl -X POST http://localhost:48293/api/seed/demo
curl -X POST http://localhost:48293/api/seed/resetMCP 클라이언트 설정
Claude Desktop
~/.claude/settings.local.json에 다음 추가:
{
"mcpServers": {
"mcp-project-manager": {
"command": "node",
"args": ["/Users/carpdm/Documents/mcp_servers/MCP_ProjectManager/packages/mcp-server/dist/index.js"]
}
}
}Claude Code
훅 핸들러는 mcp-pm setup 실행 시 자동 등록됩니다.
Cursor / VS Code
MCP 확장 프로그램 설치 후 위와 동일한 설정 사용.
개발
요구사항
- Node.js 20.0.0 이상
- Python 3.14 이상
- pnpm 9.0.0 이상
- git
빌드 명령어
# 모든 패키지 빌드
pnpm turbo build
# 개별 패키지 빌드
pnpm build -F @mcp-pm/server
pnpm build -F @mcp-pm/backend
pnpm build -F @mcp-pm/dashboard
pnpm build -F @mcp-pm/cli
# 개발 모드 (watch)
pnpm dev
# 린팅
pnpm lint
# 빌드 아티팩트 정리
pnpm clean개발 워크플로우
백엔드 시작
cd packages/backend
source .venv/bin/activate # Windows: .venv\Scripts\activate
python main.py
# http://localhost:48293에서 실행대시보드 시작
cd packages/dashboard
pnpm dev
# http://localhost:48294에서 실행MCP 서버 (로컬 테스트용)
cd packages/mcp-server
pnpm dev주요 개발 노트
- 비동기 Python: 백엔드는 SQLAlchemy 비동기 ORM 사용. 데이터베이스 호출 시 항상 await
- Greenlet 요구사항: aiosqlite + SQLAlchemy 비동기 호환성을 위해 필수
- Next.js 15 라우트: 동적 라우트 params는 Promise.
use()로 언래핑 필요 - 훅 핸들러:
packages/mcp-server/src/hooks/에 위치. Claude Code 차단 방지를 위한 fire-and-forget 패턴 - TypeScript Strict: TypeScript strict 모드 사용.
pnpm lint로 확인
기술 스택
| 레이어 | 기술 | |-------|------| | MCP Server | TypeScript, @modelcontextprotocol/sdk, tsup | | Backend | Python 3.14, FastAPI, SQLAlchemy (async), aiosqlite, greenlet | | Dashboard | Next.js 15 (App Router), React 19, TanStack Query, @dnd-kit, @xyflow/react, recharts, Tailwind CSS, date-fns | | Build | pnpm workspaces, Turborepo | | DB | SQLite (WAL mode) |
CLI 명령어
mcp-pm CLI를 통한 프로젝트 관리:
# 전체 설정: 환경 확인, 빌드, 서비스 시작, MCP 등록
mcp-pm setup
# 서비스 시작 (백엔드 + 대시보드)
mcp-pm start [service] # service: backend, dashboard, 또는 all (기본값)
# 모든 실행 중인 서비스 중지
mcp-pm stop
# 서비스 상태, 빌드, 훅, 데이터베이스 확인
mcp-pm status
# 이 프로젝트의 MCP 서버 및 훅을 Claude Desktop에서 제거
mcp-pm teardown문서
라이선스
MIT License - 자세한 내용은 LICENSE 파일 참조
Copyright (c) 2025 MCP Project Manager Contributors
감사의 글
다음 기술로 구축되었습니다:
지원
이슈 및 질문:
- GitHub Issues: https://github.com/skdkfk8758/MCP-ProjectManager/issues
- Discussions: https://github.com/skdkfk8758/MCP-ProjectManager/discussions
---
시작할 준비가 되셨나요? npx create-mcp-pm을 실행하여 Claude Code 워크플로우 추적을 시작하세요!
