ReelsFarm

@reelsfarm/mcp-client

ReelsFarm MCP サーバー用の型付き TypeScript SDK と CLI です。

バージョン 3.9

SDK 3.9.2 は ReelsFarm MCP サーバー 3.9.2 およびコントラクト 2026-10-26.1 に対応しています。公開ツール 177 件すべてを追跡します。変更および生成の結果には、ReelsFarm の明示的な来歴、実行状態、assetCreated 完了シグナルが含まれます。

バージョン 3.9 では、準備済みの各アクションを専用の確認ツールで確認します。3.7 以降のサーバーは、クライアントからの reelsfarm_confirm_action を受け付けなくなったためです。3.6 から更新してください。3.6 の確認は現在のサーバーでは失敗し、validateToolSurface: 'throw' は接続を拒否します。MIGRATION.md をお読みください。

また、スライドショーの Looks（ツイート、iMessage、ノート、雑誌の表紙）、実績のあるフォーマット、TikTok リンクからの再作成、自由なテキスト位置に対応した TikTok のテキストフォントとモード、写真検索、保存済みフォーマットとバッチ、自動化用の写真ソースと AI 画像、フックのリアクションスタイル、動画の自然な音声も追加されています。

MCP 2.x の公開用エイリアスは削除されました。公開連携を更新する前に、MIGRATION.md をお読みください。

npm install @reelsfarm/mcp-client

import { ReelsFarmClient, ReelsFarmJob } from '@reelsfarm/mcp-client';

const rf = new ReelsFarmClient({
  apiKey: process.env.REELSFARM_API_KEY,
  validateToolSurface: 'throw',
});

await rf.ready();

const avatar = await rf.avatars.generate({
  prompt: 'Woman in her 30s, casual outfit, smartphone selfie style',
  model: 'gpt-image-2.5-sunburst',
  aspectRatio: '9:16',
  quality: 'high',
});

if ('confirmationId' in avatar) {
  console.log('Review mode requires confirmation:', avatar);
} else if (avatar instanceof ReelsFarmJob) {
  const result = await avatar.wait();
}

レビュー モードでは、デフォルトで PreparedAction が返されます。その confirmationTool には、reelsfarm_confirm_generate_avatar など、確認に使用するツールが指定されています。ユーザーの承認後、confirmationId を指定してそのツールを呼び出してください。信頼されたアプリケーションでは、autoConfirm: true を設定するとレビュー アクションを自動で確認できます。Creator および Autopilot の接続では、サーバー側で管理される接続ポリシーによって有効化された機能が、SDK による追加の承認手順なしで実行されます。

Nano Banana 2.1 には nano-banana-2-1 を使用してください。従来の nano-banana-2-pro キーも 2.1 を使用します。公開 GPT Image 2.5 モデルキーには gpt-image-2.5-sunburst を使用してください。GPT Image 2 と GPT Image 2.5 では、品質に low、medium、high を指定できます。Seedream 5.0 Pro では basic または high を指定できます。Nano Banana モデルでは quality を省略してください。

ジョブの待機と公開先の検出

生成、インポート、エクスポートのステータスメソッド全13種は、{ waitMs: 25000 }を受け付けます。 0から25000までの整数を指定します。即時スナップショットを取得するには、省略するか0を指定してください。 記録された進捗に変化があった場合、ジョブが終了した場合、または待機時間の上限に達した場合に、サーバーから応答が返ります。 このオプションは、操作または公開のステータスツールには適用されません。

const snapshot = await rf.avatars.getJobStatus(jobId, { waitMs: 25000 });
// A ReelsFarmJob also supports job.getStatus({ waitMs: 25000 }).
console.log(snapshot.jobProgress);

jobProgressには、step、terminal、nextPollAfterMs、および利用可能なバッチ数が含まれます。バッチが完了した場合も、項目ごとの結果を確認してください。一部の項目が失敗していることがあります。 SDKはジョブ結果のラップを解除する際も、これらのフィールドを保持します。job.wait()は、サーバーが推奨するポーリング間隔に従い、古い形式のレスポンスにはバックオフを適用します。

公開前チェックの公開先には、settingsSchema（単一のplatformsエントリー用のJSON Schema 2020-12）、rules、limitsが含まれます。 該当するアカウントとメディアの結果に基づいて、設定を作成してください。readyはアカウントとメディアの準備状況を確認しますが、必須設定には引き続き値を設定する必要があります。limitsがない場合は不明です。連携機能の公開先では、ネイティブ接続より設定項目が少ないことがあります。コンテンツ、形式、またはアカウントを変更した場合は、公開前チェックを再実行してください。

ネイティブのInstagram動画では、instagramShareToFeed: falseに設定すると、リールをリールタブのみに表示できます。trueに設定すると、プロフィールグリッドにも表示できるようになります。新しいネイティブリールのデフォルト値はfalseです。このフィールドは、Instagram連携アカウントや写真投稿では使用できません。送信する前に、選択したアカウントのsettingsSchemaにこの項目が含まれていることを確認してください。instagramTestReelは別の設定です。

接続済みアカウントとソーシャルアカウントの一覧では、ReelsFarmの管理対象連携を通じてInstagramまたはFacebookアカウントが接続されている場合、そのアカウントにmanaged: trueと表示されます。他の連携アカウントと同じように公開してください。

対話型の生成

アバターと商品シーンのジョブは、conversationId、parentGenerationId、jobIdを返します。同じブランチを続けるには、次の生成に会話IDと親IDを渡してください。ブランチ全体は、rf.imageGenerations.getConversation(conversationId)で確認できます。

const nextAvatar = await rf.avatars.generate({
  prompt: 'Keep the same person and use a tighter crop',
  sourceImageUrl: previousImageUrl,
  conversationId,
  parentGenerationId: previousJobId,
});

フックの生成では、customPrompt、現在のすべてのVeoおよびSeedanceモデル、長さ、任意の読み上げスクリプト設定を指定できます。スライドショーの生成では、Maxモードの視覚的コンテキストを指定できます。rf.slideshows.reviseText(...)を使用すると、自然言語の指示を現在のスライドテキスト全体に適用できます。

スライドショーのテキスト生成と修正では、ダッシュボードのeffortプリセット（light、low、medium、high、extra_high）を指定できます。より高いeffortでは、より多くの視覚的参照（0、2、5、10、または20件）と、より長いモデル処理時間が必要です。extra_highでは、レンダリングされたテキストレイアウトも確認され、ダッシュボードのデフォルト設定です。effortを指定しない場合、Maxモードで使用できる視覚的参照は最大5件です。指定した場合は最大20件です。レイアウト確認では、指定がないと縦横比が1:1とみなされるため、各参照にスライドのaspectRatioを指定してください。

const textJob = await rf.slideshows.generateText({
  prompt: '8 slides about cold brew at home',
  slideCount: 8,
  maxMode: true,
  effort: 'high',
  visualContext: slideImages.map((imageUrl, order) => ({ order, imageUrl, aspectRatio: '9:16' })),
});

Look、フォーマット、再作成

generateText は Look と実績のあるフォーマットを受け取ります。デザイン済みのスライドが返されると、design オブジェクトが含まれ、テキスト項目はありません。そのまま create または update に渡してください。iMessage のスライドには写真が表示されないため、imageUrl もビジュアルコンテキストも必要ありません。auto は、プロンプトでデザインを求められた場合にのみデザイン済みの Look を選びます。

const chat = await rf.slideshows.generateText({
  prompt: 'アイスコーヒーにいくら使っているかを母が知ったときのメッセージ',
  slideCount: 4,
  design: 'imessage',
});

const picks = await rf.slideshows.generateText({
  prompt: '50ドル以下のコールドブリューメーカーおすすめ3選',
  format: 'rated-picks',
  design: 'classic',
});

rf.slideshows.recreate(...) は、公開されているTikTokの写真スライドショーを、あなたの製品向けに複製します。同じフォーマットとテキストの見た目を保ちつつ、新しい文章と各スライド用の写真を使います。完了まで約2分かかり、完了ステータスには slideshowId が含まれます。

const job = await rf.slideshows.recreate({
  tiktokUrl: 'https://www.tiktok.com/@creator/photo/7550000000000000000',
  productContextId,
  instructions: '誕生日ケーキの代わりにウェディングケーキを使う',
});

テキスト項目では、TikTok の textFont、textEffect（none、outline、background、translucent）と textColor を指定できます。これらは textStyle より優先されます。また、自由な位置を指定する textX と textY（0～1）も使用できます。searchPhotos(...) は Pinterest、Tumblr、または Pexels で写真を検索し、savePhotos(...) は選んだ写真をスライドで使える ReelsFarm の URL に変換します。saveFormat(...) と createBatch(formatId, count) を使うと、1つのフォーマットから多数のスライドショーを作成できます。アプリで「Make 10」が行うのと同じです。

動画ワークベンチ

rf.videos.generateVideo(...) は、ダッシュボードの動画ワークベンチと同じジョブを開始します。テキストからの動画生成、任意の終了フレームを指定した開始フレーム、または最大3枚の参照画像に対応しています。Seedance モデルでは、参照動画1本と参照音声ファイル1つも受け付けます。フレームと参照メディアは組み合わせないでください。フレームと参照メディアには、所有する ReelsFarm アセットの URL を使用してください。人物の開始フレームを指定すると、motionPreset によって、shocked や grateful などのリアクションを引き出すフックで動画が始まります。音声を使用する場合、naturalSpeech（デフォルトで有効）は、引用符で囲まれたセリフを、文章を変更せずに自然な話し声にします。false に設定すると、プロンプトを記述どおりに送信します。

const video = await rf.videos.generateVideo({
  prompt: '日差しの差し込むカフェのテーブルに置かれたラテに、ゆっくりと寄っていく',
  model: 'seedance-2.5',
  durationSeconds: 8,
  aspectRatio: '9:16',
  category: 'product',
});

if (video instanceof ReelsFarmJob) {
  const status = await video.wait();
  console.log(status.video?.id); // contentType UGC_VIDEO を指定して公開します。
}

モデルは seedance-2.5（デフォルト）、seedance-2、seedance-2-fast、veo-3.1、veo-3.1-fast、および gemini-omni-1.1-flash です。各モデルで、対応する動画の長さ、アスペクト比、解像度が異なります。rf.account.getGenerationPricing() は、videoGeneration の項目に秒単位の料金とともに一覧表示します。rf.videos.getGenerationStatus(jobId, { waitMs: 25000 }) でポーリングしてください。完了したジョブは、完成したライブラリ動画を video に返します。

アカウントごとに、フック、AI Clone、動画ワークベンチを通じて同時に実行できる動画ジョブは1つだけです。別のリクエストを送ると、コード VIDEO_JOB_IN_PROGRESS と実行中のジョブ名を含むエラーが返されます。そのジョブの完了を待ってから、新しい冪等性キーで再試行してください。アバターが登場するフック動画には、rf.hooks.generate(...) を使用してください。

画像テンプレート

rf.imageGenerations.listTemplates({ category }) は、ダッシュボードの「Images」ワークベンチにある「Product」と「Infographics」のテンプレートを返します。各テンプレートには、参照画像、[PLACEHOLDER] フィールドを含むプロンプト概要、呼び出す生成ツールが含まれています。プレースホルダーを置き換え、値を入力できない行は削除し、テンプレートの categoryLine でプロンプトを始めてください。

const { templates } = await rf.imageGenerations.listTemplates({ category: 'infographics' });
const [template] = templates;
if (template && !template.requiresProduct) {
  await rf.avatars.generate({
    mode: 'reference',
    sourceImageUrl: template.referenceUrl,
    prompt: `${template.categoryLine}\n${filledBrief}`,
    model: template.model,
    aspectRatio: template.aspectRatio,
    quality: template.quality,
  });
}

requiresProduct: true のテンプレートでは、sourceImageUrl に referenceUrl、productImageUrl に商品写真を設定して、rf.productScenes.generate(...) を呼び出してください。peopleTemplate は、rf.avatars.listTemplates() の人物参照画像用の概要と設定を提供します。

SDK は、ウェブコンテンツライブラリのワークフローにも直接対応しています。

const gallery = await rf.mediaCollections.listGallery({ kinds: ['COLLECTION', 'AVATAR'] });
const collections = await rf.mediaCollections.list();
const communityImages = await rf.community.listImages(collectionId, { random: true });
const voices = await rf.aiClones.listVoices({ search: 'warm' });
const importJob = await rf.hooks.importClips({
  items: [{ url: youtubeUrl, start: "0", length: "5" }],
});
const infographics = await rf.mediaCollections.listGallery({
  kinds: ['AVATAR', 'PRODUCT_PLACEMENT'],
  imageCategory: 'infographics',
  groupCollections: true,
});
const firstItems = await rf.mediaCollections.getItems(collectionId, 'all', { limit: 50 });
const { totalCount } = await rf.videos.list({ category: 'people' });

imageCategory は生成画像のみをフィルターするため、画像のみを返すように kinds を設定してください。groupCollections: true は、ダッシュボードのギャラリータブと同様に、各コレクションを1つのアイテムとして返します。コレクションのアイテムは、limit または cursor を設定しない限り、1回のレスポンスですべて返されます。設定した場合は、hasMore が false になるまで nextCursor を使って取得を続けてください。動画リストは totalCount を返し、最初のアセットページはカテゴリの totalCount を返します。ページ内の件数を数えるのではなく、これらの合計値を使用してください。

同じ MCP コントラクトで、統合ギャラリー、個人メディアコレクション、コミュニティ画像、フックのインポート状態とジョブ、AI Clone の音声検索、商品コンテキストの URL 候補、保存済みキャラクターのアイデンティティ抽出、およびクリエイティブのゴミ箱にある8種類すべてのアイテム（アバター、商品配置、動画、スライドショー、保存済みアセット、保存済みキャラクター、下書き、商品コンテキスト）を扱えるようになりました。復元時には、rf.trash.list() が返す正確なタイプと ID を使用してください。完全削除は引き続きダッシュボードでのみ行えます。

プロトコルと OAuth

SDK は安定版の MCP TypeScript SDK v2 を使用します。2026-07-28 プロトコルを確認し、必要に応じて従来の2025年のハンドシェイクにフォールバックします。

OAuth クライアントは、必要な機能だけをリクエストしてください。互換性のため、デフォルトは引き続き mcp:full です。

const rf = new ReelsFarmClient({
  oauth: {
    redirectUri: 'http://127.0.0.1:3456/callback',
    scopes: ['content:read', 'content:generate'],
    onAuthorizationUrl: openInBrowser,
  },
});

await rf.raw.listTools();
await rf.completeOAuthCallback(callbackUrl);

コールバック URL 全体を completeOAuthCallback に渡してください。SDK はコードを交換する前に、リダイレクト URL、OAuth の state、および認可サーバーの発行者を検証します。SDK は、生の認可コード完了メソッドを公開しません。この形式では state を単独で検証できないためです。

CLI

npm install -g @reelsfarm/mcp-client
reelsfarm login --api-key rfmcp_xxx
reelsfarm whoami
reelsfarm avatars list
reelsfarm avatars generate --prompt "Creator selfie style" --model gpt-image-2.5-sunburst --aspect-ratio 9:16 --quality high --wait
reelsfarm image-generations templates --category product
reelsfarm account pricing
reelsfarm videos generate --prompt "Slow push-in on a latte" --model seedance-2.5 --duration 8 --aspect-ratio 9:16 --wait
reelsfarm videos list --category product
reelsfarm media-collections gallery --kinds COLLECTION,AVATAR
reelsfarm ai-clones voices --search warm
reelsfarm hooks import-capabilities
reelsfarm posts preflight --content-type SLIDESHOW --content-id 11111111-1111-4111-8111-111111111111 --publish-format VIDEO --connection-ids 22222222-2222-4222-8222-222222222222 --agent
reelsfarm posts list --json

認証情報は、コンストラクターのオプション、環境変数、CLI 設定ファイル ~/.reelsfarm/config.json の順に参照されます。別の設定ディレクトリを使用するには、REELSFARM_CONFIG_DIR を設定してください。

AI エージェントで ReelsFarm を使用する

ReelsFarm は、エージェントモードで実行する場合、シェルを使用できるエージェントに対して安全です。

reelsfarm agent status
reelsfarm agent commands
reelsfarm social connected --agent
reelsfarm posts schedule --content-type SLIDESHOW --content-id 11111111-1111-4111-8111-111111111111 --when 2026-09-01T15:00:00Z --platforms tiktok:22222222-2222-4222-8222-222222222222 --publish-format VIDEO --agent
reelsfarm confirm conf_123 --tool reelsfarm_confirm_schedule_post --agent

--agent を使用するか、REELSFARM_AGENT_MODE=1 を設定すると、標準出力に厳密な JSON エンベロープが出力されます。エージェントモードでは、コマンド出力にテーブルや人間向けの説明文が混在することはありません。エラーも標準出力に JSON 形式で出力され、終了コードは 0 以外になります。

生成、スケジュール設定、公開、更新、削除などの準備済みアクションは、Review モードでは確認用ペイロードを返します。Creator と Autopilot は許可されたアクションをすぐに実行できます。エージェントモードが制御するのは出力のみです。確認が返された場合は、概要を確認してから、指定された nextStep を実行してください。 reelsfarm confirm <confirmationId> --tool <confirmationTool> --agent。Review モードのアクションをアプリケーションが自動的に確認する場合に限り、--yes を指定してください。 --dry-run はサーバーに送信され、--yes と併用した場合でも、Review、Creator、Autopilot の各モードで変更を加えることはできません。

直接書き込みに関するポリシーは、サーバー接続のポリシーが優先されます。Creator はコンテンツを作成・編集できますが、公開や自動化の有効化はできません。Autopilot はアカウントの上限に従って、コンテンツを公開し、自動化を管理できます。認証情報、接続モード、Webhook のセキュリティ、完全削除に関するアクションはダッシュボードでのみ行え、このパッケージでは利用できません。

冪等性と操作の復旧

SDK は、論理的な変更ごとに UUID を 1 つ生成し、トランスポートの応答が不明確な場合は同じ UUID を再利用します。プロセスの再起動後も再試行を維持する必要がある場合は、変更の入力に idempotencyKey を指定するか、CLI で --idempotency-key <key> を指定してください。異なる引数で同じキーを再利用しないでください。

SDK は、確認後にアクションを自動的に再準備することはありません。トランスポート障害により応答が不明確な場合、同じリクエストを安全に 1 回再送し、サーバーから永続的な操作が返された場合は、その操作の状態をポーリングします。

reelsfarm operations get --id op_123 --agent
reelsfarm operations wait --id op_123 --timeout 30000 --agent

構造化エラーでは、認証、スコープ不足、ポリシーによる拒否、レート制限、冪等性の競合、操作進行中、プラン上限を区別できます。拒否された自動化リクエストは、コード INVALID_AUTOMATION を持つ ReelsFarmValidationError です。実行中の動画ジョブとの競合は、コード VIDEO_JOB_IN_PROGRESS を持つ再試行可能な ReelsFarmToolError です。OAuth プロファイルは、失効するか、セキュリティイベントにより認可が必要になるまで、既存の保護されたプロファイルトークンストアにローテーションするリフレッシュトークンを保持します。

エンドポイント

デフォルトの MCP エンドポイントは https://mcp.reelsfarm.com/mcp です。別のデプロイ先を指定するには、SDK では serverUrl を、CLI では --server-url を渡します。SDK は、デフォルトでループバック以外の平文 HTTP を拒否します。allowInsecureHttp: true または REELSFARM_ALLOW_INSECURE_HTTP=1 は、信頼できるプライベートな開発用エンドポイントでのみ設定してください。CLI では --allow-insecure-http も指定できます。

開発

npm install
npm run typecheck
npm test
npm run check:manifest
npm run build

チェックイン済みのツールマニフェストには、現在検出可能な ReelsFarm MCP の機能が反映されています。ダッシュボード専用の認証情報、Webhook、完全削除のツールは、公開 SDK カタログには含まれません。マニフェストのチェックでは、両方のリポジトリが隣接している場合、公開 SDK の 177 個のツールとアプリが生成した公開ツールリファレンス、およびリリースバージョンとコントラクトバージョンをアプリの MCP サーバーと照合します。サーバーでツールが追加または削除されたときは、認証済みの MCP エンドポイントに対して npm run generate:tools を実行してください。

公開前の事前確認とプラットフォーム設定

スケジュールまたは公開の呼び出し前に事前確認を実行してください。サーバーはアクションの作成または実行前にも事前確認を繰り返します。

const readiness = await rf.posts.preflight({
  contentType: 'SLIDESHOW',
  contentId: slideshowId,
  publishFormat: 'VIDEO',
  connectionIds: [tiktokConnectionId, youtubeConnectionId],
});

const scheduled = await rf.posts.schedule({
  contentType: 'SLIDESHOW',
  contentId: slideshowId,
  publishFormat: 'VIDEO',
  scheduledFor: '2026-09-01T15:00:00.000Z',
  platforms: [{
    platform: 'TIKTOK',
    connectionId: tiktokConnectionId,
    captionOverride: 'TikTok caption',
    tiktokPublishMode: 'DIRECT',
    tiktokPrivacyLevel: 'PUBLIC_TO_EVERYONE',
    tiktokAllowComment: true,
    tiktokCommercialContentEnabled: false,
  }, {
    platform: 'YOUTUBE',
    connectionId: youtubeConnectionId,
    youtubeTitle: 'Launch Short',
    youtubePrivacyStatus: 'UNLISTED',
    youtubeMadeForKids: false,
    youtubeContainsSyntheticMedia: true,
  }],
});

CLI では、platform:connectionId 形式のシンプルなペアを指定できます。キャプションやプラットフォーム設定が必要な場合は、--platforms-json を使用してください。

公開前の投稿を編集するには、rf.posts.update(...) を使用します。既存の各公開先は platform と connectionId で指定します（rf.posts.list(...) では accountId）。省略したフィールドには保存済みの値が保持され、メディアとアカウントは変更できません。TikTok を DIRECT に切り替えるには、tiktokPrivacyLevel と、動画の場合は tiktokIsAigc が必要です。投稿の公開処理が始まると、編集は失敗します。

await rf.posts.update(scheduledPostId, {
  caption: 'New caption',
  platforms: [{
    platform: 'TIKTOK',
    connectionId: tiktokConnectionId,
    tiktokPublishMode: 'DIRECT',
    tiktokPrivacyLevel: 'PUBLIC_TO_EVERYONE',
    tiktokIsAigc: true,
  }],
});

CLI では、reelsfarm posts update --id <id> --platforms-json <json> を使用してください。

自動化

自動化の tiktokSettings では、TikTok の投稿先と同じ設定を使用できます。tiktokPublishMode、tiktokPrivacyLevel、tiktokTitle、インタラクションと情報開示のフラグ、カバー設定が含まれます。tiktokPostMode は引き続きレガシーエイリアスとして使用できます。tiktokPublishMode と tiktokPrivacyLevel は、tiktokPostMode より優先されます。

ACTIVE の自動化には、1〜90 文字の tiktokTitle と、各スライドに少なくとも 1 つの画像コレクションまたは固定画像が必要です。商用コンテンツには tiktokBrandOrganic、tiktokBrandedContent のいずれか、または両方が必要です。また、ブランドコンテンツでは SELF_ONLY のプライバシー設定を使用できません。サーバーは承認の前に各リクエストをチェックします。

実行ごとにキャプションを切り替えるには、各キャプションを角括弧で囲みます。例：[First caption][Second caption]。rf.automations.update(...) は、省略されたトップレベルのフィールドを保持し、images を置き換え、publishRules をフィールド単位でマージします。新しい caption は、保存済みの TikTok captionOverride を置き換えます。

await rf.automations.update(automationId, {
  status: 'ACTIVE',
  publishRules: {
    caption: '[Morning tip][Evening tip]',
    tiktokSettings: {
      tiktokPublishMode: 'DIRECT',
      tiktokPrivacyLevel: 'PUBLIC_TO_EVERYONE',
      tiktokTitle: 'Daily skincare tip',
    },
  },
});