plane-mcp-server

자체 호스팅 Plane(Community Edition) 을 위한 MCP(Model Context Protocol) 서버입니다. Claude에 프로젝트, 작업 항목, 상태, 라벨, 사이클, 모듈, 댓글, 활동 기록, 링크, 멤버, 인테이크 트리아지(intake triage)를 아우르는 56개의 도구를 제공하여, 로컬 채팅 세션에서 Plane 워크스페이스의 모든 프로젝트에 걸쳐 프로젝트 매니저 역할을 수행할 수 있게 해줍니다.

Plane의 공개 REST API(/api/v1)를 기반으로 구축되었으며, 문서는 developers.plane.so에서 확인할 수 있습니다. Community Edition은 프로젝트, 작업 항목, 사이클, 모듈, 인테이크, 상태/라벨을 포함합니다 — 이 서버는 해당 범위에 충실합니다. Epics, initiatives, teamspaces, customers는 Plane Commercial/Cloud 전용 기능이므로 의도적으로 포함하지 않았습니다.

설정

1. Plane API 키 생성

Plane 인스턴스에서: 프로필 설정 → 개인 액세스 토큰 → 개인 액세스 토큰 추가.

2. 의존성 설치 및 빌드

cd plane-mcp-server
npm install
npm run build

3. 환경 변수 구성

참고용으로 .env.example을 .env로 복사하세요. 단, MCP 클라이언트(Claude Desktop, Claude Code)는 이 프로세스가 로드하는 .env 파일이 아닌 자체 구성에서 환경 변수를 직접 전달합니다.

4. MCP 클라이언트에 추가

Claude Code(claude mcp add 또는 .mcp.json 편집):

{
  "mcpServers": {
    "plane": {
      "command": "node",
      "args": ["/absolute/path/to/plane-mcp-server/dist/index.js"],
      "env": {
        "PLANE_BASE_URL": "https://plane.mycompany.com",
        "PLANE_API_KEY": "plane_api_xxxxxxxxxxxxxxxxxxxx",
        "PLANE_WORKSPACE_SLUG": "acme"
      }
    }
  }
}

Claude Desktop(claude_desktop_config.json): 위와 동일한 mcpServers 블록을 사용합니다.

구성 편집 후 클라이언트를 재시작하세요. plane 서버가 연결되고 56개의 도구를 사용할 수 있게 됩니다.

Related MCP server: Plane MCP

할 수 있는 작업

• 프로젝트 — 목록/조회/생성/수정/보관/삭제, 워크스페이스의 모든 프로젝트를 한 번에 추적.

• 작업 항목(이슈) — 전체 CRUD, UUID 또는 사람이 읽을 수 있는 식별자(ENG-123)로 조회, 자유 텍스트 검색, 고급 구조화 필터 검색(상태, 우선순위, 담당자, 라벨 기준).

• 상태 및 라벨 — 각 프로젝트의 워크플로우 컬럼과 태그를 조회하고 관리.

• 사이클(스프린트) — 생성/수정/삭제, 작업 항목 할당 또는 제거, 상태 보고를 위한 진행률 수치 읽기.

• 모듈 — 사이클과 동일한 수명 주기, 장기 실행 기능 그룹용.

• 댓글 및 활동 — 토론 스레드 읽기/쓰기, 작업 항목의 필드 변경 감사 추적 읽기.

• 링크 — PR/문서/디자인을 작업 항목에 첨부.

• 멤버 — 사람의 이름/이메일을 UUID로 확인, 프로젝트 인력 배치, 역할 변경.

• 인테이크 — 백로그에 들어가기 전에 들어오는 요청 트리아지(수락/거부/보류/중복 처리).

모든 목록/조회 도구는 response_format: "markdown" | "json"을 허용합니다(기본값은 markdown, 가독성용; json은 추가 프로그래밍 사용용). 워크스페이스가 필요한 모든 도구는 PLANE_WORKSPACE_SLUG을 구성한 경우 기본값으로 사용하므로, 대부분의 호출은 project_id만 있으면 됩니다.

구현되지 않은 기능

범위를 집중적이고 CE 전용으로 유지하기 위해 의도적으로 제외했습니다: 파일/첨부 업로드, 페이지, 견적(estimates), 시간 추적(워크로그), 사용자 정의 작업 항목 유형/속성, 상업용 전용 epics/initiatives/teamspaces/customers/IDP-sync API. 이들은 src/tools/의 동일한 패턴을 따라 나중에 추가할 수 있습니다.

일반적인 다중 프로젝트 PM 세션

1. plane_list_projects — 워크스페이스의 모든 것을 확인.

2. 활성 프로젝트에서 우선순위/상태 필터로 plane_advanced_search_work_items — 긴급한 항목 찾기. 프로젝트 범위이므로 전체 워크스페이스를 커버하려면 프로젝트별로 한 번씩 호출.

3. 활성 프로젝트에서 plane_list_cycles, 그 다음 plane_list_cycle_work_items — 현재 스프린트 상태 확인.

4. plane_update_work_item — 항목을 상태 간 이동, 재할당, 우선순위 재조정.

5. plane_add_work_item_comment — 상태 메모 남기기.

6. plane_list_intake_issues + plane_update_intake_issue — 트리아지 큐 정리.

개발

npm run dev     # tsx watch, runs src/index.ts directly
npm run build   # compile to dist/
npm start       # run compiled dist/index.js

MCP Inspector로 테스트:

npx @modelcontextprotocol/inspector node dist/index.js

(Inspector의 환경 패널에서 PLANE_BASE_URL / PLANE_API_KEY / PLANE_WORKSPACE_SLUG을 설정하세요.)

엔드포인트 안정성에 관한 참고 사항

이 서버는 Plane의 호스팅 API 문서(developers.plane.so)와 문서화된 자체 호스팅 동작을 기반으로 구축되었습니다 — 자체 호스팅 인스턴스는 동일한 /api/v1 표면을 공유하지만 정확한 동작은 Plane 버전에 따라 약간 다를 수 있습니다. 덜 일반적인 도구(예: plane_advanced_search_work_items 필터 구문)가 인스턴스에서 400/404를 반환하는 경우, 더 간단한 plane_list_work_items / plane_list_states / plane_list_labels 도구를 사용하고 클라이언트 측에서 필터링하거나, 노출된 경우 <your-plane-url>/api/에서 인스턴스 자체 API 문서를 확인하세요.