craaft

Craaft MCP サーバー

Craaft 用の Model Context Protocol サーバーです。AI アシスタントから Kanban ボードを読み書きできます。

HTTP サービスとしてデプロイされます。各リクエストは呼び出し元の Authorization: Bearer ヘッダーで認証されます。認証には、cra_* の個人用アクセストークン（Craaft REST API で使用するものと同じ）か、以下のコネクターフローでサインインして発行される cro_* の OAuth アクセストークンを使用します。

craaft アカウントの二要素認証は、どちらの種類のトークンにも影響しません。アカウントのセキュリティ設定（パスワード、二要素認証、API キー）はプラットフォーム上のブラウザーでのみ変更できるため、ツールから変更することはできません。

デプロイ

cd mcp
gcloud run deploy craaft-mcp \
  --source . \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars CRAAFT_BASE_URL=https://craaft.io,MCP_PUBLIC_URL=https://ai.craaft.io/mcp

PORT 環境変数は Cloud Run によって自動的に設定されます。

Claude から接続する（OAuth）

MCP_PUBLIC_URL が設定されている場合、このサーバーは OAuth 2.1 で保護されたリソースとなるため、トークンを手動でコピーする必要はありません。

craaft は Claude ディレクトリに掲載されています。そこから接続して、手順 3 に進んでください。または、カスタムコネクターとして追加できます。

1. Claude Desktop または claude.ai で、Settings > Connectors > Add custom connector に移動します。
2. https://ai.craaft.io/mcp を貼り付けます。
3. craaft にサインインして、接続を承認します。

後からアクセスを取り消すには、Craaft の Settings > Connected apps に移動します。

設定（Claude Desktop、cra_ トークン）

1. Craaft にサインインし、Settings → API keys に移動してトークンを作成します
2. ~/.config/claude/claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "craaft": {
      "url": "https://craaft-mcp-xxxxx.a.run.app/mcp",
      "headers": {
        "Authorization": "Bearer cra_your_token_here"
      }
    }
  }
}

MCP レジストリ

craaft は公式の MCP レジストリに io.craaft/mcp として掲載されており、server.json に記載されています。craaft.io は公開鍵を https://craaft.io/.well-known/mcp-registry-auth で提供することで、io.craaft 名前空間の所有権を証明しています（プラットフォームのリポジトリ、internal/server/mcpregistry.go）。対応する秘密鍵はこのリポジトリにはありません。

変更を公開するには、server.json の version を上げてから（公開済みのバージョンは変更も再公開もできません）、次を実行します。

PRIVATE_KEY="$(openssl pkey -in ~/.config/craaft/mcp-registry-key.pem -noout -text | grep -A3 'priv:' | tail -n +2 | tr -d ' :\n')"
mcp-publisher login http --domain craaft.io --private-key "$PRIVATE_KEY"
mcp-publisher publish

レジストリのリリースから mcp-publisher をインストールしてください。

ツール

ツール	説明
list_projects	アクセス可能なすべてのカンバンプロジェクトを一覧表示します
get_board	ボードの列とカードを取得します（説明は省略されます）
get_card	説明を含む、IDで指定した単一のカードを取得します
get_card_detail	カード、コメント、イベント、チェックリスト、添付ファイルを1回の呼び出しで取得します
search_cards	プロジェクト横断でカードを検索します（説明は180文字以下の抜粋です）
create_card	列の一番下にカードを作成します。メタデータは任意で指定できます（他の人を指定しない場合は、自分に割り当てられます）
update_card	カードのタイトル、説明、列、位置、優先度、担当者、タグなどを更新します
move_card	カードを別の列またはボードに移動します
delete_card	カードを完全に削除します
add_comment	カードにコメントを追加します（@メンションに対応）
get_comments	カードのコメントを一覧表示します
get_focus	期限のあるカード、対応が必要なカード、健全性カウンターの概要を取得します
list_notifications	通知の受信トレイを新しい順に表示し、未確認件数も返します
mark_notifications_read	ID、カード、またはすべての通知を既読にします
get_me	認証済みユーザーのプロフィールを取得します
bulk_create_cards	1回のトランザクションで最大100件のカードを作成します
bulk_update_cards	1回のトランザクションで最大100件の部分的なカード更新を適用します
bulk_move_cards	最大100件のカードを列にまとめて移動します。別のボードへの移動も指定できます
rebalance_cards	1回のトランザクションで列全体の順序を並べ替えます（位置は1、2、3、...）
get_checklist	カードのチェックリスト項目を一覧表示します
add_checklist_item	カードのチェックリストに項目を追加します
update_checklist_item	チェックリスト項目のチェック状態やタイトルを変更します
delete_checklist_item	チェックリスト項目を削除します
get_card_activity	カードのアクティビティログを取得します：列やボードの移動、優先度や担当者の変更
get_board_activity	ボードのアクティビティフィードを新しい順に取得します：カードの追加、移動、アーカイブ、削除、コメント、列の変更
get_hygiene	get_focus の健全性カウンター（ghosts、stuck、mine_no_date）に該当するカードを取得します
list_attachments	カードに添付されたファイルを一覧表示します
list_board_files	ボード上のすべてのカードにあるファイルを、添付先のカードとともに検索します
download_attachment	添付ファイルのバイトデータを取得します（テキストはインライン、バイナリはbase64）
upload_attachment	インラインコンテンツからカードにファイルを添付します
delete_attachment	添付ファイルと保存済みのバイトデータを削除します
get_project	列、件数、自分のロールを含む単一のプロジェクトを取得します
create_project	ボードを作成します。テンプレートを指定することもできます（指定しない場合は、To Do／In Progress／Doneで開始します）
update_project	名前、お気に入り、公開範囲、配色、背景、テキスト色、トップバーのボタンを変更します
delete_project	ボードとその中のすべてを削除します
export_project	ボードをJSONまたはCSVとしてエクスポートします
preview_import	インポートのドライランを実行します：Trello、Jira、Asana、CSV、またはcraaftのエクスポートから作成されるボードを確認します
import_board	Trello、Jira、Asana、CSV、またはcraaftのエクスポートから新しいボードを作成します
list_board_templates	ボードテンプレートの固定カタログを一覧表示します（カンバン、スプリント、バグトラッカーなど）
add_column	ボードに列を追加します
update_column	列の名前、色、順序を変更するか、WIP制限を設定します
delete_column	空の列を削除します
archive_column	完了列のすべてのカードをアーカイブし、アーカイブしたIDを返します
archive_card	カードを削除せずにアーカイブします
restore_card	アーカイブされたカードを元の列と位置に復元します
list_archived_cards	ボードのアーカイブ済みカードを新しい順に一覧表示します
list_webhooks	ボードの送信Webhookサブスクリプションとイベントカタログを取得します
create_webhook	送信Webhookを登録します（craaft署名／Slack／Discord）
update_webhook	Webhookを一時停止／再開するか、URL、形式、イベントフィルターを変更します
delete_webhook	Webhookサブスクリプションを削除します
get_inbound_email	設定されている場合は、ボードのメールからカードへの取り込み用アドレスと、今月のAIカード利用状況を取得します
enable_inbound_email	メールからカードへの取り込みを有効にし、取り込み用アドレスを発行します
update_inbound_email	有効状態、対象の列を変更するか、トークンをローテーションします
disable_inbound_email	ボードのメールからカードへの取り込みを無効にします
list_members	ワークスペースのメンバー、ロール、ボードへのアクセス権を一覧表示します
update_member_role	メンバーのワークスペースロールを変更します
remove_member	ワークスペースからメンバーを削除します
list_invitations	保留中の招待を一覧表示します
invite_member	メールアドレスで招待します。ボードへのアクセス権も任意で付与できます
revoke_invitation	保留中の招待を取り消します
list_board_members	ボードを閲覧できるユーザーと、アクセスが明示的か暗黙的かを一覧表示します
grant_board_access	メンバーに特定のボードへのアクセス権を付与するか、ボード上のロールを変更します
revoke_board_access	明示的に付与したボードアクセス権を取り消します
update_comment	コメントを編集します（投稿者のみ）
delete_comment	コメントを削除します（投稿者、またはワークスペースのオーナー／管理者）
set_card_follow	カードのフォローを開始または解除します
list_tags	ボードのカードに付いている重複のないタグを、アーカイブ済みカードも含めて並べ替えて一覧表示します
list_milestones	ボードのマイルストーンを期限の早い順に一覧表示します
add_milestone	マイルストーンを追加します（ボード管理者のみ）
update_milestone	マイルストーンの名前や日付を変更するか、達成済みにします
delete_milestone	マイルストーンを削除します
enable_sharing	読み取り専用の公開共有を有効にし、トークンとURLを返します
disable_sharing	公開リンクを無効にします
get_avatar	ユーザーのアバターのバイトデータ、またはプレースホルダーを表示するための情報を取得します
3 つの bulk_* ツールは、すべて成功するか、すべて失敗するかのどちらかです。項目に 1 つでも不正なものがあるとバッチ全体がロールバックされ、エラーには該当するインデックスが示されるため、呼び出しに失敗してもボードが一部だけ更新されることはありません。通知メールは送信されません（アクティビティイベントとリアルタイム更新は引き続き発生します）。また、各呼び出しで 60 回分のバースト予算からレート制限トークンを 1 つ消費します。そのため、単一カード用ツールをループで呼び出すより、これらのツールを優先して使用してください。

エンドポイント

パス	目的
POST /mcp	MCP Streamable HTTP エンドポイント
GET /healthz	ヘルスチェック（{"status":"ok"} を返します）
GET /.well-known/oauth-protected-resource, GET /.well-known/oauth-protected-resource/mcp	RFC 9728 保護リソースメタデータ（MCP_PUBLIC_URL が設定されている場合のみ提供）

環境変数

変数	デフォルト	説明
PORT	8080	リッスンポート（Cloud Run によって自動設定されます）
CRAAFT_BASE_URL	https://craaft.io	上流の Craaft API URL
MCP_PUBLIC_URL	未設定（OAuth メタデータは無効）	このサーバーの公開 /mcp URL。例：https://ai.craaft.io/mcp。設定すると、RFC 9728 保護リソースメタデータを提供し、トークンがない場合や無効な場合に 401 チャレンジを返して OAuth フローを開始します。どちらの場合も、cra_ 個人アクセストークンと cro_ OAuth アクセストークンの両方を受け付けます。プラットフォームの MCP_RESOURCE_URL と一致している必要があります（比較前に両側のスキームとホストは小文字に変換され、末尾のスラッシュは削除されます）。

添付ファイル

このサーバーはリモートで動作するため、呼び出し元のファイルシステムを読み取れません。 upload_attachment ではパスではなく、コンテンツをインラインで指定します（テキストには content_text、バイナリには content_base64 を使用します）。

download_attachment は、テキスト系のコンテンツタイプを読み取り可能なテキストで返し、 それ以外はすべて Base64 エンコードで返します。添付ファイルのサイズ上限は 25 MiB ですが、 会話にインラインで含めるには大きすぎるため、max_bytes （デフォルトは 256 KiB）を超えるものは拒否し、実際のサイズを報告します。テキストは 切り捨てても読み取れるため拒否せず、切り捨てて返します。切り捨てた Base64 は読み取れないため、上限を超えるバイナリは完全にスキップされます。

添付ファイルは有料機能です。Free ワークスペースでは、アップロード時に 402 が返され、 エラーに現在のプランが示されます。まずプロジェクトの canUploadAttachments を確認してください。 これは呼び出し元ではなく、ボードのワークスペースプランを反映します。

インポート

preview_import と import_board は同じ引数を受け取ります。filename、 インラインのファイル（content_text または content_base64）、および任意の引数である source（trello、jira、asana、csv、craaft のいずれか。省略時は自動検出）、 新しいボード用の name、Craaft のフィールドとヘッダーを対応付ける CSV の mapping です。 まずプレビューしてください。プレビューでは何も書き込まず、CSV の場合は ヘッダー、推奨されるマッピング、サンプル行を返します。マッピングを指定すると 推奨内容は置き換えられるため、使用したいフィールドをすべて指定してください。import_board は 必ず新しい非公開ボードを作成し、ワークスペースのボード数上限にカウントされます （上限に達している場合は 402）。制限：5 MB、カード 2,000 件、列 200 件。添付ファイルはインポートされません。

プラットフォームの既知の仕様：アーカイブしてから削除

archive_column は isDone が設定された列のカードのみをアーカイブします。それ以外の列では エラーを返さず、archived: 0（および空の ID リスト）とともに 200 を返すため、 件数を確認してください。返された ID を使って、各カードに restore_card を実行すれば、 一括処理を取り消せます。

delete_column を妨げるのは未アーカイブのカードだけです。アーカイブ済みのカードは 削除を妨げません。ボードの最初の列に再割り当てされたうえで列が削除されるため、 カードは残り、アーカイブ状態も維持されます。（以前は失敗していました。cards_project_column_fk 制約がアーカイブ済みの行も参照していたため、削除はいつまでも 409 を返していました。 プラットフォーム側で修正済みです。）

アーカイブと復元

archive_card はカードを削除せずにボードから取り除きます。カードは引き続き検索可能で、restore_card でアーカイブされたときと同じ列・位置に戻すまで、list_archived_cards に表示されます。すでにアーカイブ済みのカードをアーカイブしたり、アーカイブされていないカードを復元したりするとエラーになります。 list_archived_cards は、get_board と同じ簡素なボード表示（説明は省略）に archivedAt を加えたもので、最大 200 件（新しい順）に制限されています。それより古いアーカイブ済みカードには、search_cards から引き続きアクセスできます。

ボードテンプレート

list_board_templates はすべての呼び出し元で同じ固定カタログを返し、プランによる制限はありません。テンプレートの key を create_project の template 引数に渡すと、その列構成でボードを作成できます。create_project のレスポンスには、テンプレートの有無にかかわらず columns は含まれません。このフィールドが設定されるのは get_project／get_board のみです。さらに、従来の todo／doing／done という列キーを設定するのはデフォルトの kanban テンプレートだけで、ほかのテンプレートではそれぞれ独自のキーが生成されます。そのため、新しいボードにカードを作成する前に get_project を呼び出してください。

Webhook とメールからのカード作成（ボード管理者、Pro）

どちらの機能も同じ条件で制限されます。ボードが表示されない場合は not found、表示されていてもボード管理者でない場合は forbidden、Free ワークスペースの場合は上限として "integrations" を示す 402 が返されます。delete_webhook と disable_inbound_email はプランによる制限がないため、これらを設定した後にダウングレードしたワークスペースでも無効化できます。

Webhook サブスクリプションの secret は、読み取りのたび（list、create、update）に全体が返され、作成後に伏せられることはありません。craaft 形式の配信では、X-Craaft-Signature ヘッダーを使って署名されます。slack と discord の配信は署名のないチャットメッセージであり、受信サービスのシークレット URL だけで認証されます。update_webhook の subscription_id 引数に指定するのはサブスクリプションの id であり、レスポンスに含まれるワークスペースレベルの endpoint_id ではありません。

メールからのカード作成では、ボードごとに 1 つの受信用アドレス（<token>@<inbound-domain>）が発行されます。送信者がワークスペースのメンバーであり、SPF／DKIM の認証に成功した場合にのみ、メールはカードになります。それ以外はすべて通知なしに破棄され、送信者にはエラーが返されません。update_inbound_email の rotate フラグを指定すると新しいトークンが発行され、古いアドレスは即座に無効になります。猶予期間はありません。

公開されていない機能とその理由

GET /projects/{id}/events はボードのSSE リアルタイムストリームであり、アクティビティログではありません。リクエスト／レスポンス形式のツールには適さない、長時間接続する text/event-stream です。ボードの履歴には get_board_activity（/projects/{id}/activity）を、カード 1 枚の履歴には get_card_activity（/cards/{id}/events）を使用してください。

ほかにも、POST /projects/{id}/cards/rebalance（内部的な位置のメンテナンス）、ボードの背景画像用エンドポイント、認証なしでアクセスできる /public/projects/{token} の読み取りは公開されていません。トークンを持つエージェントは、代わりに get_board を使用してください。