Plane

Plane MCP 서버

Plane용 Model Context Protocol 서버입니다. AI 에이전트가 프로젝트, 작업 항목, 사이클, 모듈, 릴리스, 고객 등을 읽고 관리할 수 있는 도구를 제공합니다.

FastMCP와 공식 plane-sdk 기반으로 구축되었습니다.

• 30개 도구, Plane 리소스당 하나씩, 204개 작업 포함
• 로컬 또는 원격 — stdio, streamable HTTP, SSE
• OAuth 또는 API 키 인증

빠른 시작

Plane에서 API 키를 받으세요: 워크스페이스 설정 → API 토큰.

MCP 클라이언트 구성에 다음을 추가하세요:

{
  "mcpServers": {
    "plane": {
      "command": "uvx",
      "args": ["plane-mcp-server", "stdio"],
      "env": {
        "PLANE_API_KEY": "<your-api-key>",
        "PLANE_WORKSPACE_SLUG": "<your-workspace-slug>"
      }
    }
  }
}

uvx는 설치 단계가 필요 없습니다. Python 3.10+가 필요합니다.

자체 호스팅 Plane의 경우 "PLANE_BASE_URL": "https://plane.example.com"를 추가하세요.

전송 방식

stdio — 로컬

MCP 클라이언트의 하위 프로세스로 실행됩니다. 위에 표시된 구성이 필요하며, PLANE_API_KEY와 PLANE_WORKSPACE_SLUG가 필요합니다.

PLANE_API_KEY=... PLANE_WORKSPACE_SLUG=... uvx plane-mcp-server stdio

HTTP + OAuth — 호스팅

https://mcp.plane.so/http/mcp

OAuth 흐름은 연결 시 처리되며, 구성에 자격 증명이 필요 없습니다. 네이티브 원격 MCP를 지원하지 않는 클라이언트의 경우 mcp-remote로 브리지하세요:

{
  "mcpServers": {
    "plane": {
      "command": "npx",
      "args": ["mcp-remote@latest", "https://mcp.plane.so/http/mcp"]
    }
  }
}

Node.js 22+가 필요합니다.

HTTP + 개인 액세스 토큰 — 호스팅

https://mcp.plane.so/http/api-key/mcp

헤더	값
Authorization	Bearer <PAT>
X-Workspace-slug	<workspace-slug>

{
  "mcpServers": {
    "plane": {
      "command": "npx",
      "args": ["mcp-remote@latest", "https://mcp.plane.so/http/api-key/mcp"],
      "headers": {
        "Authorization": "Bearer <PAT>",
        "X-Workspace-slug": "<workspace-slug>"
      }
    }
  }
}

SSE — 더 이상 사용되지 않음

https://mcp.plane.so/sse는 하위 호환성 목적으로만 유지됩니다. HTTP 전송 방식을 사용하세요.

도구

서버는 리소스당 하나씩 총 30개의 도구를 제공합니다. 각 도구는 작업을 선택하는 action 매개변수를 받습니다:

workitem(action="create", project_id=..., name="Fix login")
workitem(action="list", project_id=..., pql='state__group = "started"')
cycle(action="archive", project_id=..., cycle_id=...)

각 도구의 설명에는 필수 및 선택 매개변수와 함께 해당 작업이 나열되므로, 호출 시 카탈로그가 자체 문서화됩니다.

→ 전체 도구 및 작업 참조

작업 항목 쿼리

목록, 개수 및 검색은 Plane의 쿼리 언어인 PQL을 지원합니다:

workitem(action="list", project_id=..., pql='state__group = "started" AND priority = "urgent"')
workitem(action="count", pql='assignees__id = "<member id>"', group_by="state_id")

전체 구문, 연산자 및 실제 예제는 get_pql_reference를 호출하세요.

작업별 도구에서 업그레이드

이전 릴리스는 API 작업당 하나의 도구를 노출했습니다. 기존 통합은 계속 작동합니다: 177개 이름 중 169개가 여전히 통합 도구로 해석되므로, create_work_item 또는 list_cycles를 호출하는 저장된 프롬프트나 스크립트는 변경할 필요가 없습니다. 더 이상 광고되지 않지만, 원래 제공된 매개변수 이름(work_item_id, workitem_id 아님)을 유지합니다.

7개 이름은 매개변수(manage_project_archive(archive=False))로 두 작업 중 하나를 선택했는데, 이는 하나의 도구-작업 쌍으로 재현할 수 없습니다. 호출 시 대체 도구를 알려줍니다. get_pql_reference는 변경되지 않았습니다.

구성

인증

변수	필수 대상	용도
PLANE_API_KEY	stdio	API 키
PLANE_WORKSPACE_SLUG	stdio	대상 워크스페이스
PLANE_BASE_URL	선택 사항	Plane API URL (기본값 https://api.plane.so)

원격 전송 방식은 연결에 자격 증명을 포함하므로(OAuth 흐름 또는 PAT 헤더), 이 변수들이 필요 없습니다.

서버 자체를 자체 호스팅하는 경우:

변수	용도
PLANE_INTERNAL_BASE_URL	서버 간 호출용 내부 URL, PLANE_BASE_URL보다 우선
REDIS_URL	단일 연결 URL로 OAuth 토큰 저장 (TLS용 redis:// 또는 rediss://); 호스트/포트보다 우선
REDIS_HOST / REDIS_PORT	OAuth 토큰 저장; 메모리 내 저장으로 대체
PLANE_OAUTH_PROVIDER_*	OAuth 클라이언트 자격 증명 및 기본 URL
MCP_PATH_PREFIX	프록시 뒤에 마운트할 때 HTTP 라우트의 경로 접두사 — /plane는 /plane/http/mcp를 제공

OAuth 리디렉션 URI

OAuth 전송 방식은 각 클라이언트의 리디렉션 URI를 허용 목록과 대조하여 검증합니다. 일반적인 클라이언트(Cursor, VS Code, Claude.ai, ChatGPT 커넥터, localhost)는 기본적으로 허용됩니다.

릴리스 없이 새 클라이언트를 온보딩하려면 패턴을 추가하세요:

export PLANE_OAUTH_ALLOWED_REDIRECT_URIS="https://newclient.com/cb,https://other.app/oauth/*"

*는 모든 포트, 경로 세그먼트 또는 하위 도메인과 일치합니다. 호스트는 고정하고 포트나 경로만 와일드카드로 지정하세요.

로깅

구조화된 JSON. 각 도구 호출은 이름, 기간, 상태 및 가능한 경우 불투명 사용자 ID와 워크스페이스 슬러그를 기록합니다.

export LOG_USER_INFO=false    # also log the display name (PII);
export LOG_PAYLOADS=false    # keep request payloads out of logs; default true

OAuth 및 PAT 전송 방식만 표시 이름을 전달하며, stdio는 영향을 받지 않습니다.

개발

git clone https://github.com/makeplane/plane-mcp-server
cd plane-mcp-server
uv pip install -e ".[dev]"

워크스페이스에 대해 서버 실행:

PLANE_API_KEY=... PLANE_WORKSPACE_SLUG=... python -m plane_mcp stdio
python -m plane_mcp http            # port 8211

테스트, 포맷, 린트:

pytest                              # no network or credentials needed
ruff format plane_mcp/ tests/       # line length 120
ruff check plane_mcp/ tests/        # rules E, F, I, UP, B

테스트 스위트는 완전히 오프라인으로 실행됩니다 — 모든 리소스의 모든 작업이 실제 plane-sdk 시그니처에 각 호출을 바인딩하는 대체 구현에 대해 실행됩니다. plane_mcp/tools/README.md 참조.

라이브 통합 테스트는 실행 중인 서버를 가리키지 않으면 건너뜁니다:

export PLANE_TEST_API_KEY=... PLANE_TEST_WORKSPACE_SLUG=...
export PLANE_TEST_MCP_URL=http://localhost:8211    # optional; this is the default
pytest tests/test_integration.py -v

해당 워크스페이스에 실제 데이터를 씁니다.

저장소 구조

경로	내용
plane_mcp/__main__.py	진입점; argv[1]에서 전송 방식 선택
plane_mcp/server.py	전송 방식별 팩토리
plane_mcp/client.py	자격 증명을 plane-sdk 클라이언트로 해석
plane_mcp/auth/	OAuth 공급자 및 헤더 인증
plane_mcp/tools/	도구 표면: Plane 리소스당 모듈 하나
plane_mcp/toolkit/	도구 표면용 공유 빌딩 블록
plane_mcp/pql_reference.py	모델에 제공되는 PQL 구문 참조

기여

풀 리퀘스트 환영합니다. 제출 전에 pytest와 ruff check를 실행해 주세요. 새 도구는 plane_mcp/tools/README.md에 설명된 불변 조건과 함께 제공되어야 합니다.

CONTRIBUTING.md 및 CODE_OF_CONDUCT.md를 참조하세요.

Node.js 서버에서 마이그레이션

@makeplane/plane-mcp-server (Node.js)는 더 이상 사용되지 않으며 유지 관리되지 않습니다. 이 Python 구현이 이를 대체합니다.

Node.js	Python
PLANE_API_KEY	PLANE_API_KEY
PLANE_API_HOST_URL	PLANE_BASE_URL
PLANE_WORKSPACE_SLUG	PLANE_WORKSPACE_SLUG

command와 args를 빠른 시작의 stdio 구성으로 교체하세요.

라이선스

MIT — LICENSE 참조.