Skip to main content
Glama
Gyuniverse GitHub Projects MCP

Gyuniverse GitHub Projects MCP

by 4hglee-ops

GitHub Projects → Safe AI Operations → Better Team Execution

ChatGPT, Claude 같은 AI 클라이언트가 GitHub Projects v2를 조회·분석·변경·검증·감사할 수 있도록 연결하는 MCP 서버입니다.

빠른 시작 · 주요 기능 · 안전한-변경 · 아키텍처 · 문서


👀 한눈에 보기

📊 Project 상태 이해

Project item, Status, Priority, assignee, relationship과 변경 사항을 읽어 현재 팀 상태를 구조화합니다.

🛡 안전한 변경

권한, allowlist, write gate, precondition, 재조회 검증(re-read verification)을 거쳐 실제 Project를 변경합니다.

🧾 변경 추적

Checkpoint / delta와 durable audit를 이용해 변경 전후와 실행 결과를 추적합니다.

ChatGPT / Claude / MCP Client
              │
        OAuth / Remote MCP
              ▼
   Gyuniverse GitHub Projects MCP
              │
      ┌───────┼─────────┐
      │       │         │
    Read    Write   Governance
      │       │         │
      │       │         ├─ Checkpoint / Delta
      │       │         ├─ Durable Audit
      │       │         └─ Bulk Plan
      │       │
      └───────┴──────────────► GitHub Projects v2

핵심 목표는 GitHub Projects를 단순 API wrapper로 만드는 것이 아니라, AI가 실제 팀 운영 상태를 안전하게 읽고 변경할 수 있는 project operations layer를 만드는 것입니다.


Related MCP server: ContextBridge

🎯 이런 경우에 적합합니다

  • ChatGPT / Claude에서 GitHub Projects 상태를 자연어로 조회하고 싶은 경우

  • AI에게 Status / Priority 변경을 맡기되 권한과 검증 경계가 필요한 경우

  • PR merge 상태와 Project Status의 불일치를 탐지하고 싶은 경우

  • parent / sub-issue / dependency 관계를 AI workflow에서 다루고 싶은 경우

  • 여러 변경을 즉시 실행하지 않고 Preview → Approval → Apply 방식으로 통제하고 싶은 경우

  • AI가 수행한 mutation과 변경 전후 상태를 audit 가능한 형태로 남기고 싶은 경우


✨ 주요 기능

상태

기능

설명

✅

Project / field / item 조회

Projects v2 메타데이터와 현재 field 값 조회

✅

Workflow intelligence

missing Status / assignee, PR merge ↔ Project 상태 불일치 탐지

✅

Project brief

normalized snapshot 기반 팀 상태 브리핑

✅

Checkpoint / delta

기준선을 저장하고 이후 변경 사항 비교

✅

Guarded Status / Priority

고수준 write + 변경 후 재조회 검증

✅

Work item operations

item 추가, 생성, assignment 등 workflow 지원

✅

Relationship read

parent / sub-issue / blocks / blocked-by 조회

✅

Guarded relationship write

Admin 관계 추가·제거 + reciprocal verification

✅

Bulk governance

immutable Preview → Approval → Apply

✅

Durable audit

Upstash 기반 bounded write audit

✅

Role-based ACL

Viewer / Member / Admin + capability 기반 runtime authorization

✅

Remote OAuth MCP

OAuth discovery, DCR, PKCE, read/write scope 분리

✅

GPT Actions adapter

Shared Core 위의 REST/OpenAPI adapter

의도적으로 제한한 부분

AI client에서 tool이 보인다는 사실과 실제 실행 권한은 별개입니다.

Tool discovery
    ≠
Authorization

파괴적인 delete 계열 도구도 기본 surface에 제공하지 않습니다.


⚡ 빠른 시작

Maintainer-hosted endpoint

https://gyuniverse-github-projects-mcp.vercel.app/mcp

GPT Actions OpenAPI:

https://gyuniverse-github-projects-mcp.vercel.app/openapi.json

Publicly reachable ≠ publicly authorized
Endpoint가 인터넷에서 접근 가능하다는 것은 임의의 GitHub Project에 접근할 수 있다는 뜻이 아닙니다.

실제 접근은 OAuth identity, owner/Project allowlist, Project membership, capability와 write gate로 제한됩니다.

자신의 GitHub Projects를 연결하려는 외부 사용자는 일반적으로 self-hosting을 권장합니다.

Client

연결 방식

인증

지원

ChatGPT connector

Remote MCP

OAuth + PKCE

✅

Custom GPT

GPT Actions / OpenAPI

OAuth

✅

Claude Code

Remote HTTP MCP

OAuth

✅

Claude Chat / compatible connector

Remote MCP

OAuth + DCR + PKCE

✅

Local stdio

git clone https://github.com/4hglee-ops/gyuniverse-github-projects-mcp.git
cd gyuniverse-github-projects-mcp
pnpm install
cp .env.example .env
pnpm mcp:stdio

최소 read-only 예시:

GITHUB_TOKEN=github_pat_...
GITHUB_PROJECTS_ALLOWED_OWNERS=your-user-or-org
GITHUB_PROJECTS_WRITE_ENABLED=false
MCP_OAUTH_WRITE_ENABLED=false

전체 환경변수는 .env.example, 배포 방법은 docs/DEPLOYMENT.md를 참고하세요.


💡 활용 예시

현재 Project 상태 브리핑

gyuniverse-hq Project #2의 현재 상태를
진행 중 / Review / Blocker / 담당자 없는 작업으로 정리해줘.

상태 불일치 탐지

merge된 PR과 GitHub Project Status가 어긋난 항목을 찾아줘.

변경 추적

Project #2를 checkpoint와 비교해서
Status, Priority, assignee, relationship이 달라진 항목만 보여줘.

Status / Priority 변경

Issue #14의 Priority를 P0로 변경하고 결과를 다시 확인해줘.

Relationship

Issue #8과 #9의 parent / sub-issue 및 dependency 관계를 조회해줘.
Issue #9를 Issue #8의 sub-issue로 추가한 뒤 reciprocal state를 다시 검증해줘.

Bulk 변경

이 작업들의 Status / Priority 변경안을 먼저 Preview해줘.
아직 GitHub에는 적용하지 마.

승인된 plan만 Apply할 수 있습니다.


🧠 왜 만들었나

팀이 GitHub Projects를 운영하다 보면 이런 질문이 반복됩니다.

"지금 실제로 진행 중인 작업은 뭐지?"
"PR은 merge됐는데 왜 Project는 아직 In Progress지?"
"이 Issue가 다른 작업을 막고 있나?"
"AI에게 상태 변경을 맡겨도 안전할까?"
"AI가 바꾼 내용을 나중에 확인할 수 있나?"

이 프로젝트는 Project 상태를 AI가 다루기 쉬운 형태로 정규화하고, 변경이 필요하면 명시적인 안전 경계를 거쳐 GitHub operation을 수행합니다.

Project State
     ↓
Normalized Context
     ↓
AI Analysis
     ↓
Authorization / Precondition
     ↓
GitHub Mutation
     ↓
Re-read Verification
     ↓
Durable Audit

🛡 안전한 변경

기본 역할

Capability

Admin

Member

Viewer

Project read / analysis

✅

✅

✅

Status / Priority update

✅

✅

❌

Existing item add

✅

✅

❌

Item create / assign

✅

❌

❌

Generic field update

✅

❌

❌

Relationship write

✅

❌

❌

Bulk preview / approve / apply

✅

❌

❌

Identity별 permission은 role default보다 좁힐 수만 있고 확장할 수 없습니다.

Authorization path

OAuth identity + scope
        ↓
Owner allowlist
        ↓
Project allowlist
        ↓
Identity Project membership
        ↓
Operation capability
        ↓
Global write gate
        ↓
Precondition / preflight
        ↓
GitHub mutation
        ↓
Re-read verification
        ↓
Durable audit

Bulk safety

Preview
   ↓
Approval
   ↓
Apply

Apply 직전 current state와 authorization을 다시 확인하며, stale preflight가 발견되면 mutation 없이 실패합니다.

상세 내용은 docs/SECURITY.md와 docs/PERMISSIONS.md를 참고하세요.


🏗 아키텍처

flowchart TD
    C[ChatGPT / Claude / MCP Client] --> O[OAuth / MCP Adapter]
    G[Custom GPT] --> REST[REST / OpenAPI Adapter]
    O --> CORE[Shared Core]
    REST --> CORE

    CORE --> READ[Read / Project Intelligence]
    CORE --> WRITE[Guarded Operations]
    CORE --> GOV[Governance]

    READ --> GH[GitHub GraphQL API]
    WRITE --> GH
    GOV --> STORE[Upstash Durable State]

    GH --> P[GitHub Projects v2]

    GOV --> CP[Checkpoint / Delta]
    GOV --> AUDIT[Write Audit]
    GOV --> BULK[Bulk Plans]

영역

기술

Language

TypeScript

GitHub API

GraphQL

MCP

@modelcontextprotocol/server, @modelcontextprotocol/node

Validation

Zod

Runtime

Node.js

Package Manager

pnpm

Deployment

Vercel

Durable Store

Upstash Redis

자세한 구조는 docs/ARCHITECTURE.md를 참고하세요.


✅ 현재 상태

v0.2.0 / M10 Advanced Governance — Production validated

  • ✅ Local + Remote MCP

  • ✅ OAuth / DCR / PKCE

  • ✅ Shared Core + MCP / REST adapters

  • ✅ Individual identity + Viewer / Member / Admin ACL

  • ✅ High-level Project reads and writes

  • ✅ Checkpoint / delta

  • ✅ Durable audit

  • ✅ Dependency / sub-issue read

  • ✅ Guarded relationship write

  • ✅ Bulk Preview → Approval → Apply

  • ✅ Capability-based ACL

  • ✅ Production validation

현재 공개 저장소 기준 regression suite는 249 / 249 tests PASS입니다.


🧪 검증

pnpm install --frozen-lockfile
pnpm typecheck
pnpm build
pnpm test

Read-only integration smoke:

pnpm smoke:read -- gyuniverse-hq 2

HTTP runtime smoke:

pnpm smoke:http

CI는 PR / main push에서 typecheck, build, test를 수행하며 Production mutation을 요구하지 않습니다.

Public 전환 전 sanitized history를 대상으로 별도의 full-history Gitleaks 검사에서도 0 findings를 확인했습니다.


📚 문서

처음 보는 경우 docs/README.md부터 읽는 것을 권장합니다.

문서

내용

docs/ARCHITECTURE.md

전체 architecture / 요청·권한·변경 흐름

docs/SECURITY.md

보안 원칙과 authorization boundary

docs/PERMISSIONS.md

Viewer / Member / Admin 및 capability 기준

docs/DEPLOYMENT.md

Vercel / Upstash / self-hosting

docs/ROADMAP.md

현재 구현과 다음 확장 방향

docs/history/README.md

M4 → M10 개발·검증 과정 한국어 요약

CHANGELOG.md

공개 버전 변경 이력

과거 milestone 상세 원문은 docs/history/legacy/에 보존합니다.


🔐 Security

절대로 commit하지 않습니다.

- GitHub PAT / token
- OAuth signing secret
- OAuth team / access codes
- GPT Actions client secret
- Upstash credentials
- bearer / refresh tokens
- cookies / Authorization headers
- .env files

취약점을 발견한 경우 실제 credential이나 private Project data를 public issue에 올리지 마세요.


🛠 로컬 개발

요구 사항:

  • Node.js 22+

  • pnpm 10.x

  • target Projects에 접근 가능한 GitHub credential

git clone https://github.com/4hglee-ops/gyuniverse-github-projects-mcp.git
cd gyuniverse-github-projects-mcp
pnpm install
cp .env.example .env
pnpm typecheck
pnpm build
pnpm test
pnpm mcp:stdio

Remote HTTP:

pnpm mcp:http

🤝 기여

Bug report, 문서 개선, 기능 제안, Pull Request를 환영합니다.

개발 환경과 validation 기준은 CONTRIBUTING.md를 참고하세요.

Public issue/PR에 실제 token, access code, secret, private Project data를 포함하지 마세요.


🗺 장기 방향

flowchart LR
    D[Discord Bridge] --> U[Unified Team State]
    G[GitHub Projects MCP] --> U
    J[Jira] -. future .-> U
    N[Notion] -. future .-> U

    U --> C[Context]
    U --> O[Operations]
    C --> AI[AI Team Intelligence]
    O --> AI

현재는:

GitHub Projects → Read / Analyze / Safe Write / Verify / Audit

장기적으로는 Discord의 대화 맥락(Context)과 GitHub Projects의 운영 상태(Operations)를 함께 사용해 팀에서 무엇이 결정됐고, 현재 무엇이 진행 중이며, 어디가 어긋나 있는지를 근거와 함께 다루는 방향을 탐색합니다.


License

Apache License 2.0으로 공개합니다. 자세한 내용은 LICENSE를 참고하세요.


🌌 Gyuniverse

Project state → Safe operations → Better team execution

Available Tools

40 tools
add_github_project_blocked_byA
Idempotent

Make source blocked by target: target blocks source. Single relationship only. Both Issue items must belong to the same authorized Project. Requires an authenticated actor with project.write and item.relationship.write plus the global write gate. Re-reads both directions and persists audit, including no_change. Do not retry failures automatically.

Inputs: owner (required), number (required), sourceItemId (required), targetItemId (required).

add_github_project_itemA

Add an existing GitHub Issue or Pull Request node to an authorized Project v2. Disabled by default and requires an explicit Project allowlist.

Inputs: contentId (required), projectId (required).

add_github_project_sub_issueA
Idempotent

Add target as a sub-issue of source. Never replace an existing parent. Single relationship only. Both Issue items must belong to the same authorized Project. Requires an authenticated actor with project.write and item.relationship.write plus the global write gate. Re-reads both directions and persists audit, including no_change. Do not retry failures automatically.

Inputs: owner (required), number (required), sourceItemId (required), targetItemId (required).

analyze_github_project_reconciliationC
Read-onlyIdempotent

Compare Pull Request merge state with Project Status and surface evidence-backed workflow mismatches for an authorized Project.

Inputs: owner (required), number (required), first, includeArchived, +3 more.

analyze_github_project_state_gapsC
Read-onlyIdempotent

Analyze an authorized GitHub Project snapshot for missing Status and missing assignee gaps while preserving item evidence.

Inputs: owner (required), number (required), first, includeArchived, +4 more.

apply_github_project_bulk_planA
DestructiveIdempotent

Apply one approved M10-5 bulk plan once. All operations are reauthorized and re-read before the first GitHub mutation; stale/preflight failures perform zero writes. Runtime failures stop remaining operations and are never auto-retried or rolled back.

Inputs: planId (required), planDigest (required).

approve_github_project_bulk_planA
Idempotent

Explicitly approve the exact immutable bulk preview identified by plan ID and digest. The current maker-checker policy and bulk.approve capability are enforced; this does not mutate GitHub.

Inputs: planId (required), planDigest (required).

assign_work_itemA
Idempotent

Assign a GitHub user to the Issue or Pull Request represented by one authorized Project item. Admin/PM only in the current policy. Resolves the login, skips an already-assigned user, verifies the assignment, and returns actor-aware audit metadata.

Inputs: owner (required), itemId (required), number (required), assigneeLogin (required).

capture_backlogA
Idempotent

Capture an existing GitHub Issue or Pull Request URL into one authorized Project and ensure its Status is exactly 'Backlog'. If already captured in Backlog, returns no_change. Requires both item.add and item.update_status permissions before any mutation.

Inputs: url (required), owner (required), number (required).

compare_github_project_state_checkpointB
Read-onlyIdempotent

Compare the current normalized state of an allowed GitHub Project with its latest stored checkpoint without replacing that checkpoint.

Inputs: owner (required), number (required), first.

create_github_project_state_checkpointB

Capture the latest normalized state of an allowed GitHub Project as the baseline for later delta comparison. In M10 Production this baseline uses the configured durable governance store; local development may remain process-local. This does not write to GitHub.

Inputs: owner (required), number (required), first.

create_work_itemA

Create a new GitHub Issue under the same authorized Project owner, capture it into the Project, and verify exact Backlog Status. Admin/PM only in the current policy. Pre-authorizes create, add, and status permissions before Issue creation and reports a partial-failure error containing the created Issue URL if Project capture later fails.

Inputs: owner (required), title (required), number (required), repository (required), +1 more.

get_backlogC
Read-onlyIdempotent

Return items whose Project Status is explicitly Backlog.

Inputs: owner (required), number (required), first, includeArchived.

get_blockersB
Read-onlyIdempotent

Return only explicitly evidenced blockers from Blocked status/fields/reasons; does not infer blockers from ordinary workflow state.

Inputs: owner (required), number (required), first, includeArchived.

get_github_projectB
Read-onlyIdempotent

Get metadata for one GitHub Project v2 after server allowlist and authenticated Project membership checks.

Inputs: owner (required), number (required).

get_github_project_brief_contextC
Read-onlyIdempotent

Return normalized authorized Project state plus a contract for producing a team brief without treating planned work as completed work.

Inputs: owner (required), number (required), first.

get_github_project_bulk_planC
Idempotent

Read the durable state, immutable artifact, plan-level actor events and per-item results of an authorized M10 bulk plan. Project access and a bulk workflow capability are required.

Inputs: planId (required).

get_github_project_item_relationshipsA
Read-onlyIdempotent

Read native parent, sub-issue, blocks and blocked-by relationships for a GitHub Issue item in an authorized Project. Only same-Project, allowed-owner target details are returned; withheld counts and bounded coverage are explicit. Does not mutate GitHub or change get_blockers semantics.

Inputs: owner (required), itemId (required), number (required), first.

get_github_project_snapshotC
Read-onlyIdempotent

Return a normalized snapshot of an authorized Project for AI team-state analysis.

Inputs: owner (required), number (required), first.

get_identity_contextA
Read-onlyIdempotent

Return the current authenticated operator identity, role, permissions, and Project memberships without exposing access codes, bearer tokens, or secrets.

Inputs: no named parameters.

get_my_workB
Read-onlyIdempotent

Return work assigned to the authenticated GitHub identity. The optional login is accepted only as a compatibility assertion and cannot override authenticated identity.

Inputs: owner (required), number (required), first, login, +2 more.

get_project_briefC
Read-onlyIdempotent

Return a concise evidence-backed Project operating brief with status/priority counts, in-progress work, review queue, unassigned work, and explicit blockers.

Inputs: owner (required), number (required), first, includeArchived.

get_project_changesC
Read-only

Compare the current Project snapshot with the latest configured checkpoint baseline and return semantic change groups without replacing that baseline. Production may use durable M10 persistence; local development may remain process-local. Can initialize a missing baseline explicitly.

Inputs: owner (required), number (required), first, initializeIfMissing.

get_review_queueC
Read-onlyIdempotent

Return items whose Project Status is explicitly In Review.

Inputs: owner (required), number (required), first, includeArchived.

get_unassigned_workB
Read-onlyIdempotent

Return non-completed Project items with no repository or Project assignee evidence.

Inputs: owner (required), number (required), first, includeArchived.

list_github_project_fieldsB
Read-onlyIdempotent

List fields, single-select options, multi-select options, and iterations configured on an authorized GitHub Project v2.

Inputs: owner (required), number (required).

list_github_project_itemsB
Read-onlyIdempotent

List issues, pull requests, draft issues, assignees, and field values in an authorized GitHub Project v2.

Inputs: owner (required), number (required), first.

list_github_projectsB
Read-onlyIdempotent

List GitHub Projects v2 visible to the authenticated principal within the server owner/Project allowlists.

Inputs: owner (required), first.

list_github_project_write_audit_logA
Read-onlyIdempotent

List recent bounded GitHub Project write audit records. Production uses the configured durable M10 governance store; local development may remain process-local. Records contain metadata, actor identity, and verification results, not tokens or raw mutation payloads.

Inputs: limit, itemId, projectId.

preview_github_project_bulk_updatesA

Create an immutable, expiring M10-5 preview for 1-20 Status/Priority updates in one authorized Project. This performs reads and stores a plan but never mutates GitHub.

Inputs: owner (required), number (required), operations (required).

remove_github_project_blocked_byA
DestructiveIdempotent

Remove source's blocked-by relationship to target. Single relationship only. Both Issue items must belong to the same authorized Project. Requires an authenticated actor with project.write and item.relationship.write plus the global write gate. Re-reads both directions and persists audit, including no_change. Do not retry failures automatically.

Inputs: owner (required), number (required), sourceItemId (required), targetItemId (required).

remove_github_project_sub_issueA
DestructiveIdempotent

Remove target from source's sub-issues. Does not delete either Issue. Single relationship only. Both Issue items must belong to the same authorized Project. Requires an authenticated actor with project.write and item.relationship.write plus the global write gate. Re-reads both directions and persists audit, including no_change. Do not retry failures automatically.

Inputs: owner (required), number (required), sourceItemId (required), targetItemId (required).

resolve_github_issue_or_pr_urlB
Read-onlyIdempotent

Resolve an allowed github.com Issue or Pull Request URL to its GraphQL content node ID and canonical metadata.

Inputs: url (required).

resolve_github_project_itemA
Read-onlyIdempotent

Resolve an allowed GitHub Issue or Pull Request URL to the matching item in an authorized GitHub Project, following Project item pagination when needed.

Inputs: url (required), projectOwner (required), projectNumber (required).

start_workB
Idempotent

Move one authorized GitHub Project work item to the exact 'In Progress' Status using the same Shared Core write path.

Inputs: owner (required), itemId (required), number (required).

update_github_project_item_fieldA
Idempotent

Update one text, number, date, single-select, multi-select, or iteration field on an authorized Project v2 item. Disabled by default and requires an explicit Project allowlist.

Inputs: value (required), itemId (required), fieldId (required), projectId (required).

update_github_project_item_priorityB
Idempotent

Compatibility alias for the semantic Priority write path. Safely sets one item's exact Priority option by name with authorization, idempotency, verification, and actor-aware audit.

Inputs: owner (required), itemId (required), number (required), priority (required).

update_github_project_item_statusB
Idempotent

Compatibility alias for the semantic Status write path. Safely sets one item's exact Status option by name with authorization, idempotency, verification, and actor-aware audit.

Inputs: owner (required), itemId (required), number (required), status (required).

update_work_item_priorityC
Idempotent

Semantically update one authorized GitHub Project work item's Priority by exact option name. Uses Shared Core authorization, idempotency, verification, and actor-aware audit.

Inputs: owner (required), itemId (required), number (required), priority (required).

update_work_item_statusB
Idempotent

Semantically update one authorized GitHub Project work item's Status by exact option name. Uses Shared Core authorization, idempotency, verification, and actor-aware audit.

Inputs: owner (required), itemId (required), number (required), status (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.8/5.0

    Scored across 40 tools

    Disambiguation2/5

    Several tools overlap heavily, especially compatibility aliases (update_github_project_item_status vs update_work_item_status, and similarly for priority) and multiple project-state readers (get_github_project_snapshot, get_github_project_brief_context, get_project_brief, get_project_changes). An agent could easily misselect among resolution, snapshot, and brief tools.

    Naming Consistency3/5

    All names use snake_case, but the surface mixes prefixed (github_project) and unprefixed (work_item, project_brief) conventions, and includes explicit alias pairs. This remains readable but not fully predictable.

    Tool Count2/5

    40 tools is heavy for a GitHub Projects MCP, with bulk operations, audit logging, and multiple analysis layers. Each earns some place, but the count is well above a well-scoped 10–15 tool surface.

    Completeness3/5

    Core read, write, relationship, bulk, and analysis coverage is strong, but notable lifecycle gaps remain: no remove/delete Project item, no Project or field creation/mutation beyond item fields, and no draft issue creation. Agents can cover many workflows but will hit dead ends for cleanup and schema changes.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      D
      maintenance
      A policy-aware MCP server for GitHub and GitHub Actions that enables safe AI-assisted infrastructure workflows—inspecting repositories, preparing branches and pull requests, and constrained remote mutations behind explicit preview-bound approval tokens.
      18
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      A security-first MCP gateway that enables AI assistants to safely inspect and interact with GitHub repositories through a controlled, auditable tool layer with policy enforcement and human approval for mutations.
      27
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables MCP clients to read a project's Git-backed kickoff, acceptance criteria, handoff package, progress, and next step, and to append validated, audited progress events as project records. It provides short-lived scoped credentials and fail-closed tool allowlisting for safe, resumable AI-assisted development.
      -