de en es ja ko ru zh

github-project-management

Name: github-project-management
Author: jersonmartinez

by jersonmartinez

Overview Schema Related Servers Score Discussions

Python

Remote

GitHub Project Management MCP Server

MCP CI

AI 어시스턴트가 Model Context Protocol을 통해 GitHub Project V2 보드를 프로그래밍 방식으로 관리할 수 있게 해주는 커스텀 MCP(Model Context Protocol) 서버입니다. Python 3.12 및 FastMCP로 구축되었으며, stdio 전송으로 통신하고 독립형 Docker 컨테이너 안에서 실행됩니다.

위치

project/
├── mcp/                    ← This directory (root-level, independent of the app)
│   ├── Dockerfile
│   ├── requirements.txt
│   ├── server.py           # FastMCP entry point
│   ├── config.py
│   ├── auth.py
│   ├── capabilities.py     # Tool → permission mapping
│   ├── profiles.py         # Multi-target profile system
│   ├── tools/              # MCP tool definitions
│   ├── services/           # Business logic
│   ├── clients/            # GraphQL + gh CLI clients
│   ├── models/             # Pydantic models
│   ├── graphql/            # Query/mutation strings
│   ├── tests/              # Unit + contract tests
│   ├── scripts/            # Validation, preflight, secret scanning
│   │   ├── validate.sh     # ← Run before every push
│   │   ├── preflight.sh    # Environment prerequisites
│   │   ├── scan_secrets.sh # Token pattern detection
│   │   └── smoke_build.sh  # Minimal build verification
│   ├── profiles/           # Target config (.env files, no secrets)
│   ├── docs/               # Detailed documentation
│   ├── LICENSE             # MIT
│   ├── CONTRIBUTING.md
│   └── SECURITY.md

참고: 이 MCP 서버는 자체 Dockerfile, 종속성 및 수명 주기를 가진 독립 구성 요소입니다.

Related MCP server: my_pm_tools

작동 방식

MCP Client → docker run --rm -i github-project-mcp:latest → stdin/stdout JSON-RPC → GitHub API

MCP 클라이언트가 도구를 호출합니다(예: create_project_item).
docker run --rm -i github-project-mcp:latest python server.py가 실행됩니다.
서버는 인증을 검증하고 stdin을 통해 명령을 기다립니다.
클라이언트는 JSON-RPC를 stdin으로 보내고 stdout으로 응답을 받습니다.
완료되면 컨테이너는 자동으로 제거됩니다(--rm).

Docker — 빌드 및 관리

이미지 빌드

# Desde la raíz del proyecto
docker build -t github-project-mcp:latest ./mcp

Docker Compose(로컬 개발)

로컬에서 MCP를 설정하고 실행하는 가장 간단한 방법:

# 1. Crear tu configuración local (una sola vez)
cp mcp/.env.example mcp/.env
# Editar mcp/.env con tu GITHUB_TOKEN y target (org/repo/project)

# 2. Construir y verificar
cd mcp/
make build
make verify

Makefile 타깃

모든 타깃은 Docker 내에서 실행됩니다 — 호스트 의존성 없음.

cd mcp/
make help         # Mostrar todos los targets disponibles
make build        # Construir imagen Docker
make verify       # Validar auth + scopes + config
make test         # Ejecutar unit tests
make validate     # CI completo (build + syntax + tests + tools + secrets)
make tools        # Contar herramientas registradas (>= 100)
make syntax       # Verificar sintaxis Python
make secrets      # Escanear credenciales en código
make shell        # Shell interactivo dentro del contenedor
make clean        # Eliminar imágenes

참고: 호스트에서 make를 사용할 수 없는 경우 타깃을 Docker로 직접 호출할 수 있습니다. 예: docker run --rm --env-file .env github-project-mcp:latest python3 scripts/verify_setup.py

각 기여자는 저장소를 클론하고 자신의 .env를 만들기만 하면, Docker 외에 아무것도 설치하지 않고도 MCP가 작동합니다.

이미지가 존재하는지 확인

docker images | grep github-project-mcp

수동 테스트(스모크 테스트)

docker run --rm -i \
  -e GITHUB_TOKEN="<your_token>" \
  github-project-mcp:latest \
  python server.py

서버는 stderr에 github-project-management MCP server ready. Authentication validated successfully.를 출력합니다. 그런 다음 stdin을 통해 JSON-RPC를 기다립니다. 종료하려면 Ctrl+C를 누르세요.

변경 후 재빌드

docker build -t github-project-mcp:latest ./mcp --no-cache

관리 스크립트

./scripts/dev/start.sh 스크립트는 이미지를 관리하기 위한 mcp 인자를 지원합니다:

./scripts/dev/start.sh mcp build      # Construir/reconstruir la imagen
./scripts/dev/start.sh mcp test       # Ejecutar smoke test
./scripts/dev/start.sh mcp status     # Verificar si la imagen existe

참고: MCP는 지속적인 서비스가 아닙니다. up/down/restart가 필요하지 않습니다. 클라이언트가 도구를 사용할 때마다 요청 시 실행됩니다.

IDE 통합

MCP는 stdio를 통한 MCP 프로토콜을 지원하는 모든 클라이언트와 호환됩니다. 구성은 IDE에 따라 다릅니다 — 일반적인 패턴은 다음과 같습니다:

{
  "mcpServers": {
    "github-project-management": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "GITHUB_TOKEN",
        "--env-file", "mcp/.env",
        "github-project-mcp:latest",
        "python", "server.py"
      ]
    }
  }
}

IDE별 특정 구성은 docs/SETUP.md를 참조하세요.

등록된 도구(100개)

핵심 작업

도구	설명
`discover_ids`	프로젝트/필드 ID 찾기
`list_project_items`	필터로 항목 나열
`create_project_item`	이슈 생성 + 프로젝트에 추가
`update_project_item_fields`	상태, 우선순위, 마감일 업데이트
`set_estimate`	스토리 포인트 추정치 설정
`archive_project_item`	보드에서 항목 보관

이슈 관리

도구	설명
`close_issue`	이슈 닫기
`reopen_issue`	닫힌 이슈 다시 열기
`comment_issue`	이슈에 댓글 추가
`edit_issue`	제목, 본문, 라벨, 마일스톤, 담당자 편집
`add_sub_issue`	하위 이슈로 연결
`remove_sub_issue`	하위 이슈 연결 해제
`get_issue_detail`	전체 이슈 상세 정보
`search_issues`	쿼리로 검색

보드 작업

도구	설명
`move_to_status`	항목을 모든 상태 열로 이동
`move_to_done`	Done으로 표시
`move_to_trash`	휴지통으로 이동
`bulk_update_items`	여러 항목 일괄 업데이트
`bulk_close_issues`	여러 이슈 일괄 닫기
`bulk_assign`	여러 이슈 담당자 지정

계획 및 워크플로

도구	설명
`sprint_planning`	스프린트 계획 생성
`generate_release_notes`	릴리스 노트 자동 생성
`complete_issue`	전체 완료 워크플로
`daily_standup`	스탠드업 보고서 생성
`sprint_review`	스프린트 리뷰 요약
`triage_new_issues`	제안 자동 트리아지
`escalate_overdue`	기한 초과 항목에 플래그 지정
`create_epic`	상위 + 하위 이슈 생성
`close_sprint`	스프린트 종료 및 항목 이동

메타데이터

도구	설명
`create_milestone`	GitHub 마일스톤 생성
`close_milestone`	마일스톤 닫기
`list_milestones`	마일스톤 목록 표시
`create_label`	라벨 생성
`list_labels`	라벨 목록 표시
`get_project_stats`	보드 통계
`get_sprint_summary`	현재 스프린트 지표

아키텍처

Tool Layer (FastMCP tool definitions)
    ↓
Service Layer (business logic, orchestration)
    ↓
Client Layer (GraphQL + gh CLI + caching)
    ↓
GitHub APIs (GraphQL v4 + REST v3)

위임 전략

메서드	사용 시기
gh CLI	이슈 CRUD, 댓글, 프로젝트 항목 추가, 닫기
Custom GraphQL	필드 업데이트, 보관, 검색, 하위 이슈

환경 변수

변수	필수	설명
`GITHUB_TOKEN`	예	GitHub PAT(세분화된 또는 클래식)
`GH_PROJECT_ORG_NAME`	예	GitHub 소유자(조직 또는 사용자 로그인)
`GH_PROJECT_REPO_NAME`	예	저장소 이름
`GH_PROJECT_PROJECT_NUMBER`	예	Project V2 보드 번호(1–100000)

문제 해결

MCP가 연결되지 않음

# Verificar que la imagen existe
docker images | grep github-project-mcp

# Si no existe, construir
docker build -t github-project-mcp:latest ./mcp

# Verificar token
echo $GITHUB_TOKEN | head -c 20

MCP 다시 연결

MCP가 IDE에서 연결 해제되면 해당 MCP 클라이언트의 다시 연결 옵션을 사용하세요.

인증 오류

GITHUB_TOKEN이 컨테이너 환경에서 사용 가능한지 확인하세요.
github_pat_*(세분화된) 토큰에는 권한이 필요합니다: Issues(RW), Projects(RW), Metadata(R)
클래식 토큰에는 scopes가 필요합니다: repo, project, read:org

소스 위치 및 동기화

이 디렉터리(mcp/)는 MCP 패키지의 캐노니컬 소스(공식 원본) 입니다.

저장소에는 동기화된 사본이 다음 위치에 있습니다:

app/backend/app/mcp/github_project/ — Docker 빌드를 위해 백엔드에 포함됨

동기화 워크플로

먼저 mcp/에서 모든 변경을 수행합니다.
수정된 파일을 포함 경로로 복사합니다:

cp mcp/<file> app/backend/app/mcp/github_project/<file>

자동화된 검사로 검증합니다:

./mcp/scripts/check_sync.sh

동기화 스크립트는 모든 공유 .py 파일을 비교합니다(백엔드 사본에서 의도적으로 다른 __init__.py와 Dockerfile, requirements.txt 같은 인프라 전용 파일은 제외). CI는 모든 푸시에서 이 검사를 실행하며, 차이가 발생하면 빌드가 실패합니다.

백엔드 사본에서 의도적으로 다른 파일

파일	이유
`__init__.py`	백엔드 전용 임포트 + 동기화 소스 문서
`README.md`	이곳을 가리키며 복사 정책을 문서화

백엔드 테스트 스위트는 포함된 사본을 대상으로 실행됩니다. 구문 검증은 두 트리를 모두 컴파일해야 합니다.

강화된 런타임 동작

모든 설정은 GH_PROJECT_ 접두사를 사용하며 시작 시 검증됩니다:

설정	기본값	범위 / 동작
`GH_PROJECT_TIMEOUT_SECONDS`	`10`	1–120초
`GH_PROJECT_RETRY_ATTEMPTS`	`1`	0–5; 읽기 전용, 변경 작업은 재시도하지 않음
`GH_PROJECT_RETRY_DELAY_SECONDS`	`2.0`	0–60초, 지수 백오프
`GH_PROJECT_CACHE_TTL_HOURS`	`24`	1–720시간
`GH_PROJECT_CACHE_PATH`	`.github_project_cache.json`	구성 가능한 로컬 경로
`GH_PROJECT_PAGE_SIZE`	`100`	1–100
`GH_PROJECT_MAX_ITEMS`	`200`	1–1,000
`GH_PROJECT_MAX_CLI_OUTPUT_CHARS`	`1,000,000`	10,000–10,000,000

메타데이터 캐시는 원자적으로 기록되며, 소유자 전용 권한(0600)을 사용하고, 미래 타임스탬프를 거부하며, 조직이나 프로젝트 번호가 다르면 재사용되지 않습니다. CLI 및 GraphQL 진단은 토큰 형태의 값을 마스킹하고 MCP 클라이언트에 반환하기 전에 크기를 제한합니다.

Docker 전용 검증

호스트 Python 도구 없이 검증을 실행합니다:

# Compile both source copies through a Python container
tar -C . -cf - mcp app/backend/app/mcp \
  | docker run --rm -i python:3.12-slim sh -c \
    'mkdir -p /tmp/factib && tar -xf - -C /tmp/factib && \
     python -m compileall -q /tmp/factib/mcp /tmp/factib/app/backend/app/mcp'

# Run the backend MCP tests using the existing backend image
tar -C . -cf - app/backend/app app/backend/tests/mcp \
  | docker run --rm -i -e PYTHONPATH=/tmp/factib/app/backend backend:latest sh -c \
    'mkdir -p /tmp/factib && tar -xf - -C /tmp/factib && cd /tmp/factib/app/backend && \
     pytest -q --confcutdir=/tmp/factib/app/backend/tests/mcp tests/mcp'

로컬 검증(푸시 전)

PR을 생성하거나 변경 사항을 푸시하기 전에 항상 실행하세요. 이는 CI 파이프라인을 로컬에서 미러링하여 문제가 GitHub Actions에 도달하기 전에 잡아냅니다.

빠른 시작

# Full validation (builds image + runs all checks):
./mcp/scripts/validate.sh

# Quick mode (reuses cached image, skips rebuild):
./mcp/scripts/validate.sh --quick

# Auto-fix known issues (e.g., BOM characters):
./mcp/scripts/validate.sh --fix

검사 내용

단계	내용	CI 단계와 동일
1. BOM	Python 파일에서 UTF-8 BOM 바이트 감지	해당 없음(구문 오류 방지)
2. 빌드	`docker build -t github-project-mcp:validate ./mcp`	"MCP 이미지 빌드"
3. 구문	이미지 내 모든 .py 파일에 대해 `ast.parse`	"구문 검사"
4. 테스트	`tests/`에서 테스트 모듈 실행	"단위 테스트 실행"
5. 도구	등록된 도구 수 계산(100개 이상이어야 함)	"도구 수 검증"
6. 시크릿	추적된 파일에서 토큰 패턴 스캔	해당 없음(공개 전)

사용 가능한 스크립트

스크립트	용도	사용 시기
`scripts/validate.sh`	전체 CI 미러	모든 푸시/PR 전
`scripts/preflight.sh`	사전 요구사항 확인(Docker, 토큰, 구성)	초기 설정 또는 환경 변경 시
`scripts/scan_secrets.sh`	시크릿 패턴 감지	저장소 공개 전
`scripts/smoke_build.sh`	최소 빌드 + 도구 수	빠른 정상 확인
`scripts/run_contract_tests.sh`	다중 타깃 계약 테스트 스위트	구조 변경 후

일반적인 문제 및 해결 방법

문제	증상	해결 방법
BOM 문자	`SyntaxError: invalid non-printable character U+FEFF`	`./mcp/scripts/validate.sh --fix`
이미지가 빌드되지 않음	Docker 명령에서 "Image not found"	`docker build -t github-project-mcp:latest ./mcp`
토큰 미설정	사전 점검에서 "No GitHub token found"	`export GITHUB_TOKEN=ghp_...`
도구 수 < 100	새 도구가 server.py에 등록되지 않음	server.py에서 `mcp.tool()(your_tool)` 추가

구현된 작업과 계획된 작업을 포함한 전체 200개 항목 목록은 docs/HARDENING_200.md에 있습니다.

확장 기능 모음: 추가 도구 60개

이 서버는 총 100개 이상의 도구를 제공합니다. 즉, 원래의 운영 도구 40개와 tools/capability_suite.py의 특화 기능 60개로 구성됩니다.

그룹	목적	예시
이슈 및 Markdown 품질	이슈 검증, 정규화, 요약, 템플릿화, 번들 및 검토	`validate_issue_markdown`, `build_issue_template`, `build_issue_review_checklist`
댓글 시스템	진행, 계획, 차단, 해결 댓글 생성; 댓글 목록/검색/편집	`comment_issue_progress`, `comment_issue_blocker`, `list_issue_comments`
프로젝트 보고	건강도, 상태, 우선순위, 담당자, 마감일 및 필드 보고서	`project_health_report`, `project_due_date_risk`, `project_field_options_report`
프로젝트 계획	Markdown 내보내기/가져오기, 메타데이터 동기화 계획 및 필터링된 일괄 계획	`project_export_markdown`, `project_sync_issue_metadata`, `project_bulk_status_by_filter`
전략적 자동화	스프린트 계획, 백로그 순위, 리스크/의존성 보고서 및 이해관계자 업데이트	`plan_next_sprint`, `prioritize_backlog`, `generate_risk_register`
로드맵 및 의사결정	변경 로그, 릴리스 체크리스트, 로드맵, 회고 및 자동화 의사결정	`generate_changelog_from_issues`, `build_roadmap_markdown`, `build_sprint_retrospective`

광범위한 변경을 유발할 수 있는 도구는 기본적으로 dry_run 계획을 반환합니다. 직접 댓글 도구는 호출당 하나의 실제 댓글 작업을 수행합니다. 기능 카탈로그는 가져오기 시점에 60개의 고유 추가 항목을 검증하며, Docker 검증은 두 소스 사본 모두에서 등록된 FastMCP 도구 100개를 확인합니다.

배포

Docker 이미지

MCP 서버는 독립형 Docker 이미지로 배포됩니다. 로컬 빌드:

docker build -t github-project-mcp:latest ./mcp

CI/CD 파이프라인

mcp-ci.yaml 워크플로는 다음 경우에 자동으로 실행됩니다:

mcp/ 아래 파일이 변경될 때 main 브랜치로 푸시
mcp/ 경로를 변경하는 풀 리퀘스트

파이프라인 단계:

빌드 — Docker 이미지 빌드 검증
구문 검사 — 모든 Python 파일의 AST 파싱
단위 테스트 — pytest 스위트 실행
도구 수 검증 — 등록된 도구가 100개 이상인지 확인

버전 관리

이 MCP 서버는 Semantic Versioning을 따릅니다. 릴리스 기록은 CHANGELOG.md를 참조하세요.

This server cannot be installed

license - permissive license

Not graded

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

–Releases (12mo)

Commit activity

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

GitHub Projects MCP Server
Version Control Project Management Developer Tools
taylor-lindores-reeves
A
license
Not graded
quality
D
maintenance
Enables 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.
Updated a year ago (2025-09-17 19:55 UTC)
35
GPL 2.0
my_pm_tools
Project Management Version Control Workplace & Productivity
fideguch
A
license
A
quality
B
maintenance
Enables natural language management of GitHub Projects V2, including issue creation, status changes, sprint reports, and project setup via MCP tools and shell scripts.
Updated a month ago (2026-07-30 08:15 UTC)
31
1
MIT
Lazy LLMs Project Management
Project Management Version Control
Juliusolsson05
F
license
Not graded
quality
D
maintenance
Enables LLM agents to manage projects, track issues, log work, and integrate with Git. Provides 23 MCP tools for full project management capabilities.
Updated a year ago (2025-10-05 13:46 UTC)
16
GitHub Projects MCP Server
Project Management Version Control Developer Tools
Lexmata
A
license
A
quality
D
maintenance
Enables AI assistants to manage GitHub Projects V2, including items, fields, and views through a standardized interface.
Updated 4 months ago (2026-04-16 17:37 UTC)
17
12
1
MIT

View all related MCP servers

Related MCP Connectors

GitHub
Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language.
ToolAPI
Free public MCP for AI agents — 193 tools, 44 workflows. No API key.
LTD MCP
Project management MCP for AI agents with safe task reads and writes.

View all MCP Connectors

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/jersonmartinez/mcp-github-projects'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

문서	용도
docs/SETUP.md	토큰 설정 및 권한
docs/USAGE.md	도구 입력/출력 예시
docs/PARAMETERS.md	매개변수 참조
docs/TROUBLESHOOTING.md	일반적인 오류