Plane

공식

Plane 공식 MCP 서버는 Plane API와의 통합을 제공하여 Plane 프로젝트, 작업 항목, 사이클 등의 전체 AI 자동화를 가능하게 합니다.

GitHub

289

Plane MCP(으)로 무엇을 할 수 있나요?

Create work items — 프로젝트에서 workitem 액션 create를 통해 작업 항목을 생성합니다.
Query work items with PQL — workitem 액션 list/count를 사용하여 PQL(예: 상태, 우선순위)로 필터링된 작업 항목을 나열하거나 개수를 셉니다.
Get PQL reference — get_pql_reference를 통해 전체 PQL 구문과 연산자를 요청합니다.
Archive cycles — cycle 액션 archive를 사용하여 사이클을 보관합니다.

문서

Plane MCP 서버

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

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

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

빠른 시작

Plane에서 API 키를 받으세요: Workspace Settings → API tokens.

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

OAuth를 사용한 HTTP — 호스팅

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 전송 방식을 사용하세요.

도구

서버는 리소스별 하나씩 총 28개의 도구를 제공합니다. 각 도구는 작업을 선택하는 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_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=true    # also log the display name (PII); default false

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 참조.