ReelsFarm MCP server

@reelsfarm/mcp-client

Typed TypeScript SDK and CLI for the ReelsFarm MCP server.

Version 3.2

SDK 3.2.0 matches ReelsFarm MCP server 3.2.0 and contract 2026-09-16.1. It tracks all 107 public tools. Mutation and generation results now include explicit ReelsFarm provenance, execution state, and an assetCreated completion signal.

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

npm install @reelsfarm/mcp-client

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

const rf = new ReelsFarmClient({ apiKey: process.env.REELSFARMAPIKEY, 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 ('wait' in avatar) { const result = await avatar.wait(); }

Review mode returns a PreparedAction by default. 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 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. Omit quality for Nano Banana models.

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.

SDK 3.2.0 also maps the web content library workflows directly:

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" }], });

The same MCP contracts now cover the unified gallery, personal media collections, community images, hook import health and jobs, AI Clone voice search, product-context URL suggestions, saved character identity extraction, and all four web trash item types.

Protocol and OAuth

The SDK uses the stable MCP TypeScript SDK v2. It probes for the 2026-07-28 protocol and falls back to the legacy 2025 handshake when required.

OAuth clients should request only the capabilities they need. The default remains mcp:full for compatibility:

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

Shortened. The full README is on GitHub.