Planka V2

Planka v2.x MCP

Claude、Cursor、Codex、その他の MCP クライアントを Planka v2.x のボードに直接接続できます。

Model Context Protocol（MCP）を通じて、AI エージェントにプロジェクト、ボード、カード、タスク、コメント、ラベル、ワークフローへの構造化された安全なアクセスを提供します。

重要

Planka v2.x 専用に構築されています。この MCP は Planka v1.x とは互換性がありません。

Planka MCP を選ぶ理由

Planka は人間のユーザー向けに優れたウェブインターフェースを提供します。一方、AI エージェントには、プロジェクト、ボード、カード、タスク、コメント、ワークフローへの構造化されたアクセスが必要です。

この MCP サーバーは、Model Context Protocol（MCP）を通じて Planka v2 API を公開し、Claude、Cursor、Codex、その他の AI エージェントが自然言語で Planka を操作できるようにします。

対応する Planka バージョン

機能

• プロジェクトとボードの完全な管理
• カードのライフサイクル全体の管理
• タスクリストとタスクのサポート
• コメント、ラベル、割り当て
• カードの時間追跡
• プロジェクトとボードの概要
• MCP ネイティブのツールインターフェース
• 主要な MCP クライアントのサポート
• セルフホスト版およびクラウド版 Planka のサポート

✓ Created project "Website Redesign"
✓ Created board "Backlog"
✓ Created board "In Progress"
✓ Created board "Done"

Project setup completed successfully.

✓ Created card "Implement authentication"
✓ Created task list
✓ Added 4 tasks

✓ Found 7 overdue cards
✓ Moved cards to "Blocked"
✓ Added explanatory comments
✓ Generated updated project summary

card_manager の action: "get_details" には、読み取り専用のメタデータを含む attachments 配列が含まれます。メタデータには、添付ファイルとカードの ID、作成者のユーザー ID、名前、種類、MIME タイプ、サイズ、ダウンロードまたはリンクの URL、タイムスタンプが含まれます。添付ファイルの内容をダウンロードまたは返却することはありません。

クイックスタート

要件

• 実行中の Planka v2.x インスタンス
• AI エージェント専用の Planka ユーザーアカウント
• Node.js 18 以降（ローカルで実行する場合）

重要

MCP アカウントを作成した後、MCP サーバーを設定または起動する前に、そのアカウントで Planka のウェブインターフェースにログインし、 利用規約に同意してください。新しいアカウントごとに必要です。

MCP クライアントを設定する

すべての MCP 対応クライアントは同じ基本コマンドを使用します。異なるのは設定ファイルの場所（場合によっては JSON ラッパー）のみです。お使いのツールに応じた設定については、以下のクライアント設定例を参照してください。

基本の設定ブロックは常に次のとおりです。

{
  "command": "npx",
  "args": ["-y", "@goldpulpy/planka-v2-mcp@latest"],
  "env": {
    "PLANKA_BASE_URL": "https://your-planka-instance.com",
    "PLANKA_AGENT_EMAIL": "[email protected]",
    "PLANKA_AGENT_PASSWORD": "your-secure-password",
    "PLANKA_IGNORE_SSL": "true"
  }
}

{
  "command": "node",
  "args": ["/absolute/path/to/planka-v2-mcp/dist/index.js"],
  "env": {
    "PLANKA_BASE_URL": "https://your-planka-instance.com",
    "PLANKA_AGENT_EMAIL": "[email protected]",
    "PLANKA_AGENT_PASSWORD": "your-secure-password",
    "PLANKA_IGNORE_SSL": "true"
  }
}

ヒント

PLANKA_IGNORE_SSL は、信頼できるローカル環境で自己署名証明書を使用する場合にのみ "true" に設定してください。本番環境では設定しないでください。

接続を確認する

まず、エージェントに「Planka のプロジェクトを一覧表示して」のような読み取り専用の操作を依頼してください。実際の応答が返ってくれば、正しく接続されています。

クライアント設定の例

ほとんどの MCP クライアントでは、mcpServers の JSON 形式はまったく同じです。異なるのは設定ファイルの場所だけです。形式が異なるクライアント（Codex、Continue、Zed）については、以下に個別のブロックを記載しています。

{
  "mcpServers": {
    "planka-mcp": {
      "command": "npx",
      "args": ["-y", "@goldpulpy/planka-v2-mcp@latest"],
      "env": {
        "PLANKA_BASE_URL": "https://your-planka-instance.com",
        "PLANKA_AGENT_EMAIL": "[email protected]",
        "PLANKA_AGENT_PASSWORD": "your-secure-password",
        "PLANKA_IGNORE_SSL": "true"
      }
    }
  }
}

[mcp_servers.planka-mcp]
command = "npx"
args = ["-y", "@goldpulpy/planka-v2-mcp@latest"]

[mcp_servers.planka-mcp.env]
PLANKA_BASE_URL = "https://your-planka-instance.com"
PLANKA_AGENT_EMAIL = "[email protected]"
PLANKA_AGENT_PASSWORD = "your-secure-password"
PLANKA_IGNORE_SSL = "true"

codex mcp add planka-mcp -- npx -y @goldpulpy/planka-v2-mcp@latest

mcpServers:
  - name: planka-mcp
    command: npx
    args:
      - -y
      - "@goldpulpy/planka-v2-mcp@latest"
    env:
      PLANKA_BASE_URL: https://your-planka-instance.com
      PLANKA_AGENT_EMAIL: [email protected]
      PLANKA_AGENT_PASSWORD: your-secure-password
      PLANKA_IGNORE_SSL: "true"

{
  "context_servers": {
    "planka-mcp": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "@goldpulpy/planka-v2-mcp@latest"],
      "env": {
        "PLANKA_BASE_URL": "https://your-planka-instance.com",
        "PLANKA_AGENT_EMAIL": "[email protected]",
        "PLANKA_AGENT_PASSWORD": "your-secure-password",
        "PLANKA_IGNORE_SSL": "true"
      }
    }
  }
}

npx -y @goldpulpy/planka-v2-mcp@latest

セキュリティ

• 認証には専用の Planka ユーザーアカウントを使用します。
• 認証情報は環境変数のみを通じて渡されます。
• MCP サーバーは、実行中のプロセス外にボードデータを保存しません。
• SSL 証明書の検証はデフォルトで有効です。
• PLANKA_IGNORE_SSL=true は、信頼できるローカル環境またはセルフホスト環境でのみ使用してください。

トラブルシューティング

開発

# Install dependencies
npm install

# Configure environment variables
cp .env.example .env

# Start the bundled Planka development instance
npm run planka:up

# Build the project
npm run build

# Run @modelcontextprotocol/inspector
npm run inspector

開発用インスタンスには Docker Compose が必要です。http://localhost:3000 で利用できます（ログイン：[email protected] / admin）。ローカルで使用するには、.env の URL とログイン情報を更新してください。新しく作成した MCP アカウントと同様に、MCP サーバーでアカウントを使用する前に、ブラウザーからサインインして利用規約に同意してください。データを保持したままインスタンスを停止するには npm run planka:down を実行します。インスタンスを停止してボリュームを削除するには npm run planka:clear を実行します。

デモボードのシード

開発専用のシードコマンドを使うと、ローカルでのテストやデモに適したボードを作成できます。実行前にプロジェクトの依存関係をインストールし、アクセス可能な Planka v2 インスタンスと有効な PLANKA_BASE_URL、PLANKA_AGENT_EMAIL、PLANKA_AGENT_PASSWORD の値を .env に設定してください。

# Reuse or create the private "Demo Project", then create "Demo Board"
npm run seed

# Seed an existing project
npm run seed -- --project-id <project-id>

# Choose a different board name
npm run seed -- --project-id <project-id> --board-name "My Demo Board"

# Show all options
npm run seed -- --help

ボードには、デフォルトのワークリストにまたがるカード、説明、相対的な期限、タグとして使われる Planka ラベル、タスクリスト、完了済みおよび未完了のタスク、コメントが含まれます。コマンドが成功すると、プロジェクト ID、ボード ID、ボード名、リソース数が表示されます。

シードコマンドは、指定した名前と完全に一致するボードがすでに含まれているプロジェクトの変更を拒否します。別の名前を選ぶには --board-name を使用してください。ボード作成後にエラーが発生した場合、コマンドは失敗した段階とボード ID を報告し、途中まで作成されたボードを確認できる状態で残します。同じ名前で再試行する前に、そのボードを Planka で削除してください。

シードのソースと、別途コンパイルされる .seed-dist/ 出力は開発専用であり、MCP サーバーのビルドや公開パッケージには含まれません。

コントリビューション

コントリビューションを歓迎します。詳細は CONTRIBUTING.md をご覧ください。

謝辞

このプロジェクトは Navya-Tecnologia/planka-v2-mcp のフォークであり、同プロジェクトは bradrisse/kanban-mcp を基盤としています。このコードベースの基盤を築いてくださった @virapa と @bradrisse に感謝します。

ライセンス

MIT License の下でライセンスされています。詳細は LICENSE をご覧ください。

このプロジェクトは MCP インターフェースのみに特化しています。Planka サーバー自体のセットアップについては、Planka の公式ドキュメントをご覧ください。