Favro

favro-mcp

Go で記述された、Favro 用の Model Context Protocol サーバーです。

stdio 経由で MCP をやり取りし、Favro の REST API を型付きツール 86 個として公開します。基本的な CRUD に加え、自然言語での利用を想定したワークフローツール（検索、名前から ID への解決、説明のピンポイント編集）を備えているため、LLM は検索の往復にレート制限の枠を費やさずに Favro を操作できます。すべての変更を伴うツールで dry_run をサポートしています。

非公式です。 Favro との提携や、Favro による推奨を受けていません。

要件： ソースからビルドするには Go 1.27.3、Favro アカウントと API トークンが必要です。リリース履歴については、CHANGELOG.md を参照してください。

インストール

Claude Desktop バンドル

各タグ付きリリースでは、GitHub Releases ページに favro-mcp_<version>.mcpb が公開されます。これを開くと、サーバーが Claude Desktop にインストールされ、必要な 3 つの値（Favro のメールアドレス、API トークン、組織 ID）の入力を求められるため、設定ファイルを手動で編集する必要はありません。

また、設定ファイルで指定する 2 つの項目も尋ねられます。破壊的なツール（enable_destructive）は有効にするまでオフのままで、アップロードもアップロードフォルダー（upload_dir）を選択するまで無効です。このサーバーはツールの呼び出し前に確認を求めません。Claude Desktop が各ツールを承認し、常に許可したツールは確認なしで実行されるため、そのツールが必要でない限り enable_destructive はオフのままにしてください。

バンドルには、macOS ユニバーサルバイナリ、Windows amd64 バイナリ、および起動時に選択するランチャーを介した Linux の両アーキテクチャが含まれます。checksums.txt に記載され、リリース署名によって検証されています。ダウンロードの検証を参照してください。

Cowork プラグイン（推奨）

各タグ付きリリースでは、GitHub Releases ページに複数アーキテクチャ対応の favro-mcp.plugin zip が 1 つ公開されます。バンドルには darwin-amd64、darwin-arm64、linux-amd64、linux-arm64、windows-amd64 向けのバイナリが含まれます。macOS と Linux ではランチャーのシムが実行時に適切なバイナリを選択し、Windows では .cmd のシムが windows-amd64 バイナリを実行します。これは Windows on arm64（windows-arm64）上でエミュレーションにより動作します。

1. リリースから favro-mcp.plugin をダウンロードします。
2. Cowork プロファイルにインストールします（ドラッグ＆ドロップするか、Cowork のプラグインインストール手順に従います）。
3. 認証します（以下の認証を参照）。
4. Cowork を再起動すると、すべてのツールが登録された favro MCP サーバーが表示されます。

バンドル内の .mcp.json は ${CLAUDE_PLUGIN_ROOT}/bin/favro-mcp を参照するため、インストール先を移動できます。ホストのパスを編集する必要はありません。

スタンドアロンバイナリ

Cowork 以外のホスト（未加工の .mcp.json を介した Claude Code、MCP Inspector、カスタム連携）向けです。

1. リリースから、対応する favro-mcp_<version>_<os>_<arch>.tar.gz（Windows の場合は .zip）をダウンロードします。
2. 展開し、favro-mcp バイナリを $PATH 上の場所に置きます（または絶対パスを控えておきます）。
3. 認証します。
4. MCP ホストの設定でバイナリを指定します。以下のMCP ホストの設定を参照してください。

ソースから

git clone https://github.com/mmedum/favro-mcp
cd favro-mcp
make build       # → bin/favro-mcp

Go 1.27.3 が必要です。これは go.mod で宣言されているバージョンです。デフォルトの GOTOOLCHAIN=auto では、古いツールチェーンを使用している場合に必要なバージョンがオンデマンドでダウンロードされます。GOTOOLCHAIN=local では、ダウングレードせずにビルドが失敗します。

ダウンロードの検証

すべてのリリースには、checksums.txt、各アーカイブの SBOM、チェックサムファイルに対する鍵なしの cosign 署名、および GitHub によって証明されたビルドの来歴情報が含まれています。.mcpb バンドルはアーカイブとともに checksums.txt に含まれているため、1つの署名ですべてを検証できます。

# 1. The file is what the release says it is.
sha256sum -c checksums.txt --ignore-missing

# 2. The checksum file came from this repository's release workflow.
cosign verify-blob checksums.txt \
  --bundle checksums.txt.bundle \
  --certificate-identity-regexp '^https://github\.com/mmedum/favro-mcp/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

# 3. Which workflow, at which commit, built a given artifact.
gh attestation verify favro-mcp_<version>_<os>_<arch>.tar.gz --repo mmedum/favro-mcp

ビルドは再現可能です。-trimpath とコミット独自のタイムスタンプを使用しているため、タグから再ビルドすると、バイト単位で同一のアーカイブが生成されます。

認証

サーバーは Favro の HTTP Basic Auth（ユーザーのメールアドレス＋API トークン）を使用し、起動時に1つの Favro 組織にスコープを限定します。ツールが organization_id を受け取ることはありません。環境変数またはキーリングで一度指定すれば、あとは意識する必要はありません。

API トークンはユーザー単位です。チームでインストールする場合は、個人アカウントではなく、必要最小限の権限を設定した専用のサービス用 Favro ユーザーからトークンを生成してください。

認証情報の解決

2つのソースを順に確認します。完全な (email, token, organization_id) の組み合わせを最初に提供したソースが使用されます。

1. 環境変数 — FAVRO_USER_EMAIL、FAVRO_API_TOKEN、FAVRO_ORGANIZATION_ID。
2. OS キーリング — favro-mcp auth login で一度設定します（クロスプラットフォーム対応：macOS Keychain、Windows Credential Manager、Linux Secret Service）。

次の4つの変数は、サーバーの実行主体ではなく、実行方法を変更します。

変数	効果
FAVRO_LOG_LEVEL	debug／info（デフォルト）／warn／error。ログは stderr に出力され、stdout には MCP プロトコルストリームのみが出力されます。
FAVRO_MCP_SKIP_VALIDATE	true に設定すると、認証情報を Favro に対して確認する起動時の呼び出しを省略します。オフラインテスト用です。この場合、サーバーは起動時ではなく、最初の実際のツール呼び出し時に失敗します。false、0、および true として読み取れない値では、確認は有効のままです。
FAVRO_ENABLE_DESTRUCTIVE	true に設定すると、削除ツールと favro_widen_collection_sharing という破壊的なツールが登録されます。デフォルトでは無効です。「無効」とは、ガードされるのではなく、tools/list に表示されないことを意味します。自動承認モードのホストは確認を求めずにツールを実行するため、ツールを登録しないことが唯一の保証です。値を true として読み取れない場合、これらのツールは無効のままです。各呼び出しでは confirm: true も渡す必要があります。
FAVRO_UPLOAD_DIR	アップロードツールがファイルを読み取る唯一のディレクトリを、絶対パスで指定します。未設定の場合、これらのツールは登録されません。このディレクトリの外側は読み取られず、ディレクトリ外を指すリンクも拒否されます。

認証情報を含むすべての変数は、値の前後の空白を除いて読み取られ、空白だけの値は未設定として扱われます。

FAVRO_REQUIRE_PROMPT は削除されました。false 以外に設定するとサーバーは起動を拒否するため、設定を解除してください。FAVRO_INTERACTION_HINT も削除されました。false に設定すると、警告とともに無視され、マークされたツールはそのマークを維持します。

呼び出しの承認

各呼び出しを承認するのは MCP クライアントです。サーバーが自ら確認を求めることはありません。 claude.ai と Codex は destructiveHint が付いた破壊的なツールについて確認を求め、VS Code は書き込みを行うすべてのツールについて確認を求めます。

Claude Code では、設定にかかわらず、次の5つのツールは呼び出しのたびに確認を求めます。 favro_delete_tag、favro_delete_group、favro_delete_widget、favro_delete_collection は、削除した対象だけにとどまらない損失をもたらす可能性があり、favro_widen_collection_sharing はコレクションを組織全体、またはリンクを知っている人なら誰でもアクセスできるようにします。claude -p のように確認を表示できない場合、Claude Code はこれらの呼び出しを拒否します。それ以外については、設定の permissions.ask に承認したい呼び出しを1つずつ列挙し、favro の代わりにサーバーに付けた名前を指定します。たとえば、共有、公開、ファイル送信、削除を行う書き込みの場合は次のとおりです。

{
  "permissions": {
    "ask": [
      "mcp__favro__favro_create_collection", "mcp__favro__favro_update_collection",
      "mcp__favro__favro_widen_collection_sharing",
      "mcp__favro__favro_create_group", "mcp__favro__favro_update_group",
      "mcp__favro__favro_upload_attachment", "mcp__favro__favro_upload_comment_attachment",
      "mcp__favro__favro_delete_tag", "mcp__favro__favro_delete_group",
      "mcp__favro__favro_delete_widget", "mcp__favro__favro_delete_collection",
      "mcp__favro__favro_delete_column", "mcp__favro__favro_delete_card",
      "mcp__favro__favro_delete_comment", "mcp__favro__favro_delete_task",
      "mcp__favro__favro_delete_tasklist", "mcp__favro__favro_delete_webhook",
      "mcp__favro__favro_remove_attachment", "mcp__favro__favro_replace_dependencies",
      "mcp__favro__favro_delete_dependency", "mcp__favro__favro_delete_all_dependencies"
    ]
  }
}

クライアントがどのような動作をしても、次の制約が適用されます。

• 破壊的なツールは、要求された場合にのみ使用できます。 FAVRO_ENABLE_DESTRUCTIVE=true の場合にのみ利用でき、各呼び出しには confirm: true が必要です。dry_run: true を指定すると、確認なしでプレビューできます。
• 共有は組織内に限定されます。 通常のコレクション、グループ、ウィジェットの書き込みで共有できるのは、userId で指定された組織メンバーと、メンバーで構成されるグループのみです。メールでの招待、新しい管理者、組織外のユーザー、組織外のユーザーを含むグループ、ウィジェットのオーナーまたは編集者としてのゲスト、公開コレクションや組織全体に公開されたコレクションは拒否されます。 favro_widen_collection_sharing はコレクションを公開します。また、コレクションの ID だけでなく名前も受け取るため、確認画面にどのコレクションかが表示されます。
• 省略して削除対象が広がることはありません。 favro_delete_widget には collection_id または everywhere: true が必要で、どちらも指定されていない呼び出しは拒否されます。

auth サブコマンド

favro-mcp auth login       # interactive: masked token input, writes to keyring
favro-mcp auth status      # show user/org (token never printed)
favro-mcp auth logout      # delete keyring entries
favro-mcp auth which       # print active credential source: env or keyring
favro-mcp doctor           # check credentials, org binding and API reachability
favro-mcp doctor --show-ids  # the same, unredacted, for your own screen
favro-mcp --version        # print version + commit
favro-mcp --dry-run        # process-wide override: forces all writes into dry-run

favro-mcp auth login は、キーリングを使う方法の初回セットアップ用コマンドです。トークンを更新するには、再度実行してください。

何かがうまく動作しない場合は、まず favro-mcp doctor を実行してください。ビルド情報、認証情報の取得元、Favro が認証情報を受け入れるかどうか、組織 ID がトークンから実際に参照できる組織を示しているかどうかを報告します。最後の問題があると、すべてのツールが not_found を返す状態になります。出力では ID とアドレスが一貫したプレースホルダーに置き換えられるため、課題に貼り付けられます。--show-ids を指定すると、自分の画面に実際の値が表示され、その旨も示されます。

MCP ホストの設定

バイナリまたはプラグインを配置し、認証情報を保存したら、MCP ホストの設定にサーバーを登録します。

デフォルト（キーリングを使用し、設定にシークレットを含めない方法）：

{
  "mcpServers": {
    "favro": { "command": "/path/to/favro-mcp" }
  }
}

ヘッドレス／CI（環境変数） — シェルからシークレットを渡します。値を直接記述することはありません。

{
  "mcpServers": {
    "favro": {
      "command": "/path/to/favro-mcp",
      "env": {
        "FAVRO_USER_EMAIL": "${FAVRO_USER_EMAIL}",
        "FAVRO_API_TOKEN": "${FAVRO_API_TOKEN}",
        "FAVRO_ORGANIZATION_ID": "${FAVRO_ORGANIZATION_ID}"
      }
    }
  }
}

Cowork プラグインには ${CLAUDE_PLUGIN_ROOT}/bin/favro-mcp を参照する独自の .mcp.json が含まれているため、このインストール方法では手動で設定する必要はありません。

レート制限

Favro は、組織ごとにプラン別のレート制限を適用します（Lite は約100回／時、Standard は約1000回／時、Enterprise は約10000回／時）。問題のあるエージェントは、組織内の全員が使う枠を使い果たす可能性があります。サーバーはタグ、ユーザー、ウィジェット、列の解決結果をメモリ内にキャッシュし、必要に応じてキャッシュを破棄するための force_refresh をすべての一覧／解決ツールでサポートしています。一覧ツールがページを自動で集約することはありません。各 next_page には明示的な後続呼び出しが必要なため、LLM は必要に応じて早期に処理を止められます。

ドライラン

変更を行うすべてのツールは dry_run: true を受け付けます。Favro に接続せず、実行される HTTP リクエスト（メソッド、URL、本文）と状態差分の予測を返します。読み取りツールでは dry_run を受け付けません。

サンドボックス環境でのテストや、自律実行前のテストでは、バイナリに --dry-run を指定すると、呼び出しごとの入力にかかわらず、プロセス全体でドライランモードが強制されます。

ツール

Favro REST のすべてのリソースを網羅する 86 個のツールに加え、自然言語での利用に適したワークフローツールを用意しています。詳細なリファレンスについては、docs/TOOLS.md をご覧ください。

まず知っておきたいツール：

ツール	機能
favro_search_cards	カード名と説明を全文検索します。ウィジェットまたはコレクションを対象に指定できます。
favro_get_card_full	ID をすべて名前に解決したカードを 1 件取得します。後続の呼び出しを 4～7 回省けます。
favro_resolve_*	タグ、ユーザー、コレクション、ウィジェット、列、カスタムフィールド、グループの名前を ID に変換します。
favro_append_card_description	説明をピンポイントで編集し、統合差分を返します。
favro_ping	ローカル診断を行います。バージョン、紐付けられた組織、認証情報の取得元を確認します。Favro には接続しません。

トラブルシューティング

まず favro-mcp doctor を実行してください。以下の項目のほとんどに直接回答し、その出力は安全に issue に貼り付けられます。

症状	診断と対処
認証情報は受け入れられるのに、すべてのツールが [not_found] を返す	FAVRO_ORGANIZATION_ID に、このトークンから参照できない組織が指定されています。favro-mcp doctor はこれを組織の紐付けエラーとして報告します。favro-mcp doctor --show-ids を実行すると、トークンから参照できる ID が一覧表示されます。
起動時に authentication failed — check FAVRO_USER_EMAIL and FAVRO_API_TOKEN env vars が表示される	認証情報が設定されていないか、トークンが取り消された、またはローテーションされています。favro-mcp auth which を実行して、サーバーがどの認証情報ソースを読み取っているか確認し、favro-mcp auth login を再実行する（キーリングを使用する場合）か、環境変数を更新してください。
起動時に FAVRO_ORGANIZATION_ID is required が表示される	このサーバーは設計上、単一の組織のみを対象とします。起動前に、すべてのリクエストの対象となる組織を指定する必要があります。FAVRO_ORGANIZATION_ID を設定する（または auth login に含める）と、再起動してください。
HTTP 429／rate limit exceeded	組織ごとの Favro レート制限に達しました。クライアントは Retry-After を尊重して一度再試行します（上限は 30 秒）。その後、retry_after_seconds を含む型付きエラーを返します。追加のリクエストを消費せずに直近の X-RateLimit-* ヘッダーを確認するには、favro_rate_limit_status を使用してください。
next_page が null 以外の値を返し続ける	リスト取得ツールは自動集約を行いません。後続の各呼び出しには page と同じ request_id を指定する必要があります（Favro は X-Favro-Backend-Identifier を介してページ分割された読み取りをルーティングします）。ツールによっては、元のフィルターも再送する必要があります。
decodeJSONLenient が content-type: text/html, body-prefix: "<p>It looks like…" を含むエラーを返す	ドキュメントに記載された API の範囲に存在しない Favro エンドポイントにアクセスしました。Favro は 404 ではなく SPA のフォールバックページを返します。エラーにはステータス、content-type、body-prefix が含まれるため、1 回の往復で原因を診断できます。
カスタムフィールドへの書き込みが 200 を返すのに値が変わらない	原因として知られているものが 2 つあります。1 つ目は、そのフィールドがウィジェットで有効になっていないことです。組織全体のカスタムフィールドでも Favro UI でウィジェットごとに有効にする必要があり、そのウィジェットにないフィールドへの書き込みは受け入れられますが無視されます。2 つ目は、Favro が不明なボディフィールドを黙って無視するため、型ごとの形式が誤っていても成功したように見えることです。favro_set_card_custom_field は Favro の REST ドキュメントに記載された形式を送信しますが、すべてが実際のテナントで確認されているわけではありません。favro_get_card_full でカードを再読み込みして確認してください。
書き込みの成功後も、ツールの説明に古いデータが表示される	キャッシュの無効化はすべて、組織とリソースタイプごとに行われます。書き込みに成功したのに次の読み取りで古いデータが表示される場合は、リスト取得ツールまたは解決ツールに force_refresh: true を指定してください。
Linux ランチャーがプラグインから実行できない	ランチャーは bash スクリプトです。シェルから実行できない場合は、.mcp.json で ${CLAUDE_PLUGIN_ROOT}/bin/linux-amd64/favro-mcp（または linux-arm64）を直接指定してください。
Windows	同梱の bin/favro-mcp.cmd shim は bin\windows-amd64\favro-mcp.exe を実行します。Windows ホストでは PATHEXT により ${CLAUDE_PLUGIN_ROOT}/bin/favro-mcp が自動的に .cmd に解決されるため、MCP ホストの設定にある標準の .mcp.json 設定をそのまま使用できます。ホストが PATHEXT に対応していない場合は、command に ${CLAUDE_PLUGIN_ROOT}/bin/favro-mcp.cmd（または bin/windows-amd64/favro-mcp.exe）を直接指定してください。

ドキュメント

docs/TOOLS.md	すべてのツール、その入力、および返される内容です。
docs/configuration.md	すべての設定、コマンド、および起動時の動作です。
docs/security.md	信頼境界、ログに記録される内容、および制限の仕組みです。
docs/development.md	ゲート、テストの規約、およびリリースの作成方法です。
docs/architecture.md	設計、決定済みの制約、エビデンスログ、およびフェーズ計画です。
SECURITY.md	脆弱性の報告方法です。

開発

ゲートとテストの規約については docs/development.md を、環境のセットアップ方法とプルリクエストの作成方法については CONTRIBUTING.md をご覧ください。

ライセンス

Apache 2.0 — LICENSE と NOTICE をご覧ください。