planka-mcp

Claude Code에서 15개의 MCP 도구를 통해 Planka 2.x 보드를 제어하세요. 쓰기 작업은 다시 읽고 검증되므로, 보고된 성공은 보드와 일치합니다. 선택적 워크플로는 해당 보드를 에이전트 작업을 위한 지속적 메모리로 전환합니다.

Leer en español

You talk to Claude Code
          │
          ▼
  planka-mcp (stdio) ─── HTTPS + JSON ───▶ Planka 2.x
          │                                  │
          └──── reads the result back ◀──────┘

[!WARNING] 기존 @gogogadgetbytes/planka-mcp 패키지는 Planka 2.x에서 아무 작업도 수행하지 않으면서 성공을 보고할 수 있습니다. 기존 설치를 교체하기 전에 네 가지 무음 실패 함정을 읽으세요.

MCP가 처음이신가요? 먼저 읽어보세요

MCP는 Claude Code가 다른 프로그램이 제공하는 도구를 호출할 수 있게 하는 표준입니다. 이 저장소는 해당 도구 호출을 Planka API 요청으로 변환하는 작은 로컬 프로그램을 실행합니다. 전용 Planka 사용자로 작동하므로 Planka 자격 증명이 필요합니다. Claude 자체가 아닙니다. 자격 증명은 사용자 머신에 남아 있으며 프로젝트 수준의 .mcp.json 파일에 기록되지 않습니다. Claude Code는 세션이 시작될 때 MCP 서버를 로드하므로 설정 또는 구성 변경 후 다시 시작하세요.

Related MCP server: Planka MCP Server

요구 사항

• Node.js 18 이상 및 npm

• 접근 가능한 Planka 2.x 인스턴스

• 대상 프로젝트와 보드를 볼 수 있는 전용 Planka 사용자

• claude로 설치 및 사용 가능한 Claude Code

• 설정이 보드를 생성해야 하는 경우에만 프로젝트 관리자 역할

Linux와 macOS가 지원됩니다. Bun 런타임은 필요하지 않습니다.

5분 설치

저장소를 클론하고 안내형 설치 프로그램을 실행하세요:

git clone https://github.com/omnicoreos/planka-mcp.git
cd planka-mcp
./scripts/setup.sh

설정은 Planka URL, 에이전트 이메일 또는 사용자 이름, 비밀번호를 묻습니다. 구성 작성 전에 해당 자격 증명을 검증하고, 보드를 선택하거나 생성할 수 있게 하며, 실제 생성/라벨/댓글/삭제 스모크 테스트를 실행합니다.

두 가지 Claude Code 구성을 제공합니다:

두 경우 모두 설정은 자격 증명을 Git 외부의 ~/.config/planka-mcp/config.json에 모드 0600으로 저장하고 개인 실행기 ~/.local/bin/planka-mcp를 생성합니다. 생성된 팀 구성에는 비밀번호가 포함되지 않습니다:

{
  "mcpServers": {
    "planka": {
      "type": "stdio",
      "command": "${HOME}/.local/bin/planka-mcp",
      "args": []
    }
  }
}

설치 프로그램은 다시 실행해도 안전합니다. planka 항목을 업데이트하고, 기존 워크플로 목록과 라벨을 재사용하며, 임시 스모크 테스트 카드를 삭제합니다.

작동 확인

먼저 Claude Code의 구성을 확인하세요:

claude mcp list
claude mcp get planka

그런 다음 Claude Code를 완전히 다시 시작하세요. .mcp.json을 선택한 경우 해당 프로젝트에서 Claude Code를 열고 프롬프트가 표시되면 프로젝트 범위 서버를 승인하세요.

Claude Code에 요청하세요:

Show me my Planka projects and boards. In the Pending list, create a card named
"MCP is working" with the description "Created from Claude Code", then read it back.

Claude가 도구를 볼 수 없으면 먼저 다시 시작한 다음 문제 해결을 따르세요.

15개 도구

ID는 문자열입니다. planka_get_structure로 시작한 다음 Planka가 반환한 ID를 사용하세요. 추측하지 마세요.

모든 입력 필드와 모든 도구의 전체 페이로드는 도구 참조에 있습니다.

선택적 에이전트 워크플로

MCP 서버는 단독으로 작동합니다. 선택적 방법은 다른 문제를 해결합니다: 에이전트 세션 간에 작업이 존재하는 이유, 변경된 사항, 여전히 유효한 사항을 보존하는 것입니다.

계층적으로 도입하세요:

1. MCP 도구만 사용합니다.

2. 보드 상태, 카드 템플릿, 인간 핸드셰이크를 추가합니다.

3. 디렉터가 작업자를 조정하는 카드당 워크트리를 하나씩 추가합니다.

세션을 견디는 보드로 시작하세요. 보드 템플릿, 복사 가능한 Claude Code 스킬, 선택적 워크트리 헬퍼는 독립적인 구성 요소입니다.

문제 해결

• 증상, 원인 및 정확한 해결 방법

• Planka 2.x가 기존 MCP 서버를 조용히 깨뜨리는 이유

• 전체 도구 페이로드

버그를 보고할 때는 Planka 버전, Node 버전, 도구 이름, 오류 텍스트를 포함하세요. 자격 증명이나 액세스 토큰은 절대 붙여넣지 마세요.

크레딧 및 라이선스

이 프로젝트는 gogogadgetbytes/planka-mcp의 MIT 라이선스 포크이며, 처음부터 새로 구현한 것이 아닙니다. 업스트림 귀속, 유지 관리된 수정 사항, 미해결 풀 리퀘스트는 CREDITS.md를 참조하세요.

원본 및 현재 기여자 고지는 LICENSE를 참조하세요.

개발

npm ci
npm run build
npm test

실제 스모크 테스트는 쓰기 가능한 보드를 변경한 후 스스로 정리하므로 옵트인 방식입니다:

export PLANKA_BASE_URL="https://planka.example.com"
export PLANKA_AGENT_EMAIL="agent@example.com"
export PLANKA_AGENT_PASSWORD="<YOUR_PASSWORD>"
export PLANKA_SMOKE_BOARD_ID="1234567890123456789"
npm run test:smoke

변경 사항을 열기 전에 CONTRIBUTING.md를 참조하세요. 릴리스 정체성은 project.identity.json에 중앙 집중화되어 있습니다. 자체 네임스페이스로 게시하기 전에 업데이트하고 npm run sync:identity를 실행하세요.