@reelsfarm/mcp-client

Typed TypeScript SDK and CLI for the ReelsFarm MCP server.

Version 3.11

SDK 3.14.0 matches ReelsFarm MCP server 3.14.0 and contract 2026-11-08.1. It tracks all 177 public tools. Mutation and generation results include explicit ReelsFarm provenance, execution state, and an assetCreated completion signal.

Server 3.11 lists the same tools in about a quarter of the old size. Confirmation tools take only confirmationId, so a dry-run client no longer calls them. Read MIGRATION.md for the other changes.

Version 3.9 confirms each prepared action with its own confirmation tool, because servers since 3.7 no longer accept reelsfarm_confirm_action from clients. Update from 3.6: its confirmations fail against the current server, and validateToolSurface: 'throw' refuses to connect. Read MIGRATION.md.

It also adds slideshow Looks (tweet, iMessage, notebook, magazine cover), proven formats, Recreate from a TikTok link, TikTok text fonts and modes with free text positions, photo search, saved formats and batches, the automation photo sources and AI pictures, hook reaction styles, and natural speech for Videos.

Publishing aliases from MCP 2.x are removed. Read MIGRATION.md before you update a publishing integration.

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();
}

Review mode returns a PreparedAction by default. Its confirmationTool names the one tool that confirms it, such as reelsfarm_confirm_generate_avatar; call it with the confirmationId after the user approves. Trusted applications can set autoConfirm: true to confirm Review actions automatically. Creator and Autopilot connections execute the capabilities enabled by their server-owned connection policy without an extra SDK approval step.

Use nano-banana-2-1 for Nano Banana 2.1. The legacy nano-banana-2-pro key also uses 2.1. Use gpt-image-2.5-sunburst as the public GPT Image 2.5 model key. GPT Image 2 and GPT Image 2.5 accept low, medium, or high quality. Seedream 5.0 Pro accepts basic or high. FLUX 3 (flux-3) accepts basic (1K), high (about 2 megapixels), ultra (2K), or max (4K); bigger sizes cost more credits, and the prepared result's estimate follows the size. Omit quality for Nano Banana models.

Job waits and publishing discovery

All 13 generation, import, and export status methods accept { waitMs: 25000 }. Use an integer from 0 through 25000. Omit it or use 0 for an immediate snapshot. The server returns when recorded progress changes, the job ends, or the wait budget expires. This option does not apply to operation or publish status tools.

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

jobProgress contains step, terminal, nextPollAfterMs, and available batch counts. Inspect item results even when a batch completes; some items can fail. The SDK preserves these fields when unwrapping job results. job.wait() follows the server's suggested polling delay, with backoff for older responses.

Publishing preflight targets include settingsSchema (JSON Schema 2020-12 for one platforms entry), rules, and limits. Build settings from the exact account and media result. ready checks account and media readiness; required settings still need values. Missing limits are unknown. Integration targets can expose fewer settings than native connections. Run preflight again after changing the content, format, or account.

For a native Instagram video, set instagramShareToFeed: false to keep the Reel in the Reels tab only. Set it to true to also allow it on the profile grid. New native Reels default to false. This field is not available for Instagram integration accounts or photo posts. Check that the selected account's settingsSchema includes it before sending it. instagramTestReel is a separate setting.

Connected and social account lists mark an account managed: true when ReelsFarm connected the Instagram or Facebook account through its managed integration. Publish to it like any other integration account.

Conversational generation

Avatar and product-scene jobs return conversationId, parentGenerationId, and jobId. Pass the conversation and parent IDs into the next generation to continue the same branch. Read the complete branch through 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,
});

Hook generation accepts customPrompt, all current Veo and Seedance models, duration, and optional spoken script settings. Slideshow generation accepts Max mode visual context. Use rf.slideshows.reviseText(...) to apply a natural language instruction to the complete current slide text state.

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗