Claude kickflow連携の設定方法とできること

Claude kickflow連携とは — 何ができるか

kickflowは、稟議申請や複雑な承認ルート設計、組織図管理を扱うクラウド型のワークフローシステムです。申請や承認のフローをシステム上で電子化し、誰の承認待ちで止まっているかを可視化する用途で導入されています。Claude kickflow連携とは、kickflow公式が公開するMCPサーバー(@kickflow/mcp-server)をClaude Codeに接続し、会話からkickflow APIを呼び出せるようにする仕組みです。

接続すると、「チケットIDxxxの申請内容を確認して」「カテゴリの一覧を教えて」のような依頼を、kickflowの管理画面を開かずに処理できます。BacklogのMCPサーバーが機能ごとに個別のツール名を持つのに対し、kickflowのMCPサーバーは3つの汎用ツールでAPI全体を操作する設計です。この違いが、後半で扱う権限設計の難しさに直結します。

kickflowのアクセストークンを発行し、Node.jsを確認する

接続にはkickflowのアクセストークンが必要です。発行手順はkickflow公式ヘルプの記事にあります。発行したトークンは環境変数として渡します。このヘルプ記事はこちらの環境から取得できず、画面の操作手順や付与できる権限の範囲までは照合できていません。

MCPサーバーの実行にはNode.js v22.18.0以上が必要です。npmレジストリ上の最新版(1.5.3)の engines にも node >=22.18.0 と書かれており、READMEと一致します。バージョンが古いと起動に失敗するため、node --version で事前に確認しておきます。複数のNode.jsを切り替えて開発している環境では、Claude Codeを起動するシェルで有効なバージョンが要件を満たしているかも見ておきます。

Claude CodeにkickflowのMCPサーバーを追加する

追加には claude mcp add を使います。オプションの意味やスコープの使い分けはClaude Code MCP設定ガイドにまとまっています。

claude mcp add --transport stdio \
  --env KICKFLOW_ACCESS_TOKEN=your-kickflow-access-token \
  kickflow -- npx -y @kickflow/mcp-server

--env は複数の KEY=value を受け取る形式なので、サーバー名を --env の直後に書くと名前まで環境変数の組として読まれて拒否されます。上のコマンドは間に --transport stdio を挟んでこの落とし穴を避けています。-- より後ろは、フラグも含めて丸ごとサーバーの起動コマンドとして渡されます。

v2.1.287の claude mcp add --help では、--scope の既定値が local と表示されました。何も指定しなければ、トークンを含む設定は現在のプロジェクトだけに紐づく形で保存されます。チームで共有したくないトークンを project スコープ(.mcp.json)にそのまま書くと、リポジトリに入る点に注意が要ります。

Windows環境では npx を直接呼ぶ代わりに cmd /c でラップします。READMEのJSON設定例も、OSごとに起動コマンドが分かれています。

Claude Desktopなど他のMCPクライアント向けの設定ファイル(claude_desktop_config.json)でも、mcpServers オブジェクトの中身は同じ構造です。

接続先を変えたい場合のために、READMEは3つの環境変数を挙げています。

3つの汎用ツールで稟議・ワークフローを操作する

公開されているツールは discover_apis / get_api_info / call_api の3つだけです。これらを組み合わせて、kickflow APIのほぼ全機能に間接的に届きます。

Claudeはこの流れを依頼文から自動で組み立てるので、利用者が3つのツールを指定する必要はありません。たとえば「チケットID 550e8400-e29b-41d4-a716-446655440000 の内容を教えて」と頼めば、内部で getTicket が呼ばれます。READMEの call_api 入力例は次のとおりです。

{
  "operationId": "getTicket",
  "pathParams": { "ticketId": "550e8400-e29b-41d4-a716-446655440000" }
}

一覧系の例では、listTickets に queryParams として page と perPage を渡しています。作成系では createCategory の requestBody に {"name": "新しいカテゴリ"} を渡します。入力の形を覚える必要はなく、依頼文だけで組み立てが完結する点がこの設計の利点です。

専用ツール型と汎用ツール型で何が違うのか

kickflow APIはOpenAPIスキーマで定義されており、discover_apis と get_api_info は、パッケージに同梱されたスキーマ由来の定義を参照して情報を返します。そのためAPIが増えても、MCPサーバー側にツールを足す作業が要りません。実際、npmレジストリの公開履歴を見ると、2025年5月の初版から39回のバージョンが出ており、最新の1.5.3は2026年9月24日の公開です。ツール名を増やさない構成は、この更新ペースと相性がよい設計です。

どちらが優れているというより、サービスの性質に合わせたトレードオフです。汎用ツール型を採るサーバーに接続するときは、権限の細かさを利用者側で補う前提で導入を考えると、想定外の操作に後から気づく事態を避けやすくなります。

call_apiの権限をどこまで絞れるか

get_issue と delete_issue が別名になるサーバーと違い、kickflowでは読み取りも書き込みも call_api という1つのツール名を通ります。Claude Codeの権限ルールで mcp__kickflow__call_api を許可・確認・拒否にしても、効く範囲は操作の種類ではなくツール全体です。

権限ルールの基本はMCPセキュリティガイドに任せ、ここでは operationId で絞る2つの方法を確認します。Claude Backlog連携のように個別ツール名で制御できるサーバーとは、設計が異なります。

方法1: --disallowedToolsでoperationIdを拒否する

公式のパーミッション仕様では、MCPツールの引数に基づく拒否ルールは --disallowedTools で渡す形です。設定ファイルの deny に mcp__ で始まる括弧付きルールを書いても、読み込み時に無視され、無効な設定として警告されます。

引数の条件は、ツール入力の最上位のフィールドにしか使えません。call_api の入力では operationId が最上位にあり、requestBody の中身は入れ子なので対象外です。値は完全一致が基本で、* をワイルドカードに使えます。

claude --disallowedTools "mcp__kickflow__call_api(operationId:createCategory)"

この方法は、拒否したい operationId を事前に把握している必要があります。READMEに載っている名前は listCategories・createCategory・getTicket、入力例の listTickets だけです。実際の一覧は discover_apis の出力で確かめます。書き込み系には approveTicket・rejectTicket・deleteUser などがあり、稟議の承認や却下も call_api を通ります。上のコマンドは、その名前の拒否が仕様上書ける形を示した例です。

方法2: PreToolUseフックで読み取り系だけ通す

拒否ルールが「列挙した名前を止める」方式なのに対し、フックなら「許可する名前だけ通す」方式にできます。PreToolUse フックはMCPツールにも効き、マッチャーには mcp__kickflow__.* のようにサーバー単位の正規表現を書けます。フックに渡るJSONの tool_input から operationId を読み、条件に合わなければ permissionDecision を deny で返します。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__kickflow__call_api",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/kickflow-readonly.sh" }
        ]
      }
    ]
  }
}

スクリプト側の判定は、jq で operationId を取り出し、get・list で始まるものだけ素通しにする形です。

#!/bin/bash
# .claude/hooks/kickflow-readonly.sh
OP=$(jq -r '.tool_input.operationId')
 
case "$OP" in
  get*|list*) exit 0 ;;   # 判断を出さず、通常の権限フローに任せる
  *)
    jq -n --arg op "$OP" '{
      hookSpecificOutput: {
        hookEventName: "PreToolUse",
        permissionDecision: "deny",
        permissionDecisionReason: ("読み取り以外のAPIは許可していません: " + $op)
      }
    }' ;;
esac

get* と list* という前提は、READMEの例にある命名(getTicket・listCategories)に合わせたものです。リポジトリのAPI定義は全96件で、読み取り系のうちこの規則に当てはまらないのは lookupUserByEmail でした。上のスクリプトではこれも拒否されるため、通したい場合は case に足します。

スクリプトには chmod +x .claude/hooks/kickflow-readonly.sh で実行権限を付けます。フックの詳しい書き方はClaude Code hooksガイドにあります。

exit 0 で何も返さない場合は、フックが判断を出さないだけで、通常の権限ルールがそのまま働きます。読み取り系の確認画面を省きたいときは、call_api に ask ルールを置かず、フックで読み取り系に allow、それ以外に deny を返す設計になります。ask ルールを残すと、フックが allow を返しても確認は出ます。

段階的に緩める進め方

読み取り専用で使いたいからといって、call_api を禁止すると照会までできなくなります。まず ask で始め、依頼の実行内容をしばらく観察し、問題なければ ask ルールを外し、フックで読み取り系だけ通す、という順番が扱いやすいです。トークン側でも権限は絞れますが、どの範囲を付与できるかはkickflowのヘルプで確認する必要があります。

つまずきやすい点と原因の切り分け

接続できているのにAPIが失敗するときは、MCPサーバーではなくkickflow REST APIの仕様が原因のことがあります。kickflow開発者サイトのトラブルシューティングには、次の症状が載っています。call_api の queryParams や requestBody を組み立てるClaudeにも当てはまる内容です。

特にチケット更新では、「承認者による上書き」が既定の「承認者用フィールドのみ上書き可能」だと、「承認者が入力可能」にチェックの付いたフィールドだけをリクエストボディに含める必要があります。「すべてのフィールドを上書き可能」なら、すべてのフィールドを含めます。更新に失敗したときは、フォーム側の設定とリクエストの中身を突き合わせると原因が絞れます。

ほかにも、次のような状況があります。

• Node.jsのバージョンが古くて起動しない: v22.18.0未満では要件を満たしません。nvm などで上げてから再実行します
• Windowsで npx が起動しない: READMEの設定どおり、command を cmd、先頭の引数を /c にします
• get_api_info で引数が分からない: 先に discover_apis で正しい operationId を確認してから呼びます
• 社内プロキシ経由でしか届かない: KICKFLOW_API_BASE_URL と KICKFLOW_API_HEADERS で接続先と追加ヘッダーを指定できます
• operationId が多くて探しにくい: 「チケットに関するAPIを教えて」のように機能名で絞って頼むと見つけやすくなります
• 一覧の結果が途中で切れる: Claude Codeは、MCPツールの出力が10,000トークンを超えると警告を出し、既定で25,000トークンまでに制限します。listTickets のように件数の多い応答では、perPage を小さくするか、MAX_MCP_OUTPUT_TOKENS で上限を上げます

補足: 他のMCPサーバーと併用するとき

他のMCPサーバーと併用しても、ツール名は mcp__kickflow__call_api のようにサーバー名つきです。call_api という汎用的な名前が衝突する心配はありません。