Fal.ai MCP Server

Instructions

Implementation Reference

• src/fal_mcp_server/handlers/image_editing_handlers.py:371-448 (handler)

  Main execution logic for the resize_image tool. Parses arguments, validates format/mode, determines target dimensions using SOCIAL_MEDIA_FORMATS, and routes to mode-specific helpers (extend via AI outpainting, placeholders for crop/letterbox).
  async def handle_resize_image( arguments: Dict[str, Any], registry: ModelRegistry, queue_strategy: QueueStrategy, ) -> List[TextContent]: """Handle the resize_image tool for Canva-style image resizing.""" target_format = arguments["target_format"] mode = arguments.get("mode", "extend") # Determine target dimensions if target_format == "custom": if "width" not in arguments or "height" not in arguments: return [ TextContent( type="text", text="❌ Custom format requires both 'width' and 'height' parameters.", ) ] target_width = arguments["width"] target_height = arguments["height"] format_label = f"custom ({target_width}x{target_height})" else: if target_format not in SOCIAL_MEDIA_FORMATS: return [ TextContent( type="text", text=f"❌ Unknown format: {target_format}. Available formats: {', '.join(SOCIAL_MEDIA_FORMATS.keys())}", ) ] format_info = SOCIAL_MEDIA_FORMATS[target_format] target_width = format_info["width"] target_height = format_info["height"] format_label = f"{target_format} ({target_width}x{target_height})" logger.info( "Resizing image to %s using mode=%s", format_label, mode, ) if mode == "extend": # Use AI outpainting to extend the image return await _resize_with_outpainting( arguments, target_width, target_height, format_label, registry, queue_strategy, ) elif mode == "crop": # Smart crop to target dimensions return await _resize_with_crop( arguments, target_width, target_height, format_label, registry, queue_strategy, ) elif mode == "letterbox": # Add letterbox bars return await _resize_with_letterbox( arguments, target_width, target_height, format_label, registry, queue_strategy, ) else: return [ TextContent( type="text", text=f"❌ Unknown resize mode: {mode}. Use 'extend', 'crop', or 'letterbox'.", ) ]
• src/fal_mcp_server/tools/image_editing_tools.py:148-208 (schema)

  JSON schema definition for the resize_image tool, including social media presets, custom dimensions, resize modes, and supporting parameters.
  Tool( name="resize_image", description="Resize/reformat images for different platforms (like Canva Magic Resize). Uses AI outpainting to intelligently extend content for new aspect ratios. Note: 'crop' and 'letterbox' modes coming soon.", inputSchema={ "type": "object", "properties": { "image_url": { "type": "string", "description": "URL of the source image (use upload_file for local images)", }, "target_format": { "type": "string", "enum": [ "instagram_post", "instagram_story", "instagram_reel", "youtube_thumbnail", "youtube_short", "twitter_post", "twitter_header", "linkedin_post", "linkedin_banner", "facebook_post", "facebook_cover", "pinterest_pin", "tiktok", "custom", ], "description": "Target platform format, or 'custom' to specify dimensions", }, "width": { "type": "integer", "minimum": 64, "maximum": 4096, "description": "Custom width in pixels (required if target_format='custom')", }, "height": { "type": "integer", "minimum": 64, "maximum": 4096, "description": "Custom height in pixels (required if target_format='custom')", }, "mode": { "type": "string", "enum": ["extend", "crop", "letterbox"], "default": "extend", "description": "How to handle aspect ratio change: extend (AI outpainting - recommended), crop (coming soon), letterbox (coming soon)", }, "background_prompt": { "type": "string", "description": "For 'extend' mode: prompt to guide AI-generated extended areas (e.g., 'continue the beach scenery')", }, "background_color": { "type": "string", "default": "#000000", "description": "For 'letterbox' mode: hex color for bars (e.g., '#FFFFFF' for white)", }, }, "required": ["image_url", "target_format"], }, ),
• src/fal_mcp_server/server.py:61-85 (registration)

  Registration of the resize_image handler in the central TOOL_HANDLERS dictionary used by the MCP server's call_tool method to route tool calls.
  TOOL_HANDLERS = { # Utility tools (no queue needed) "list_models": handle_list_models, "recommend_model": handle_recommend_model, "get_pricing": handle_get_pricing, "get_usage": handle_get_usage, "upload_file": handle_upload_file, # Image generation tools "generate_image": handle_generate_image, "generate_image_structured": handle_generate_image_structured, "generate_image_from_image": handle_generate_image_from_image, # Image editing tools "remove_background": handle_remove_background, "upscale_image": handle_upscale_image, "edit_image": handle_edit_image, "inpaint_image": handle_inpaint_image, "resize_image": handle_resize_image, "compose_images": handle_compose_images, # Video tools "generate_video": handle_generate_video, "generate_video_from_image": handle_generate_video_from_image, "generate_video_from_video": handle_generate_video_from_video, # Audio tools "generate_music": handle_generate_music, }
• src/fal_mcp_server/tools/image_editing_tools.py:12-26 (helper)

  Preset dimensions for social media formats used by the resize_image handler to map target_format strings to width/height.
  SOCIAL_MEDIA_FORMATS = { "instagram_post": {"width": 1080, "height": 1080, "aspect": "1:1"}, "instagram_story": {"width": 1080, "height": 1920, "aspect": "9:16"}, "instagram_reel": {"width": 1080, "height": 1920, "aspect": "9:16"}, "youtube_thumbnail": {"width": 1280, "height": 720, "aspect": "16:9"}, "youtube_short": {"width": 1080, "height": 1920, "aspect": "9:16"}, "twitter_post": {"width": 1200, "height": 675, "aspect": "16:9"}, "twitter_header": {"width": 1500, "height": 500, "aspect": "3:1"}, "linkedin_post": {"width": 1200, "height": 627, "aspect": "1.91:1"}, "linkedin_banner": {"width": 1584, "height": 396, "aspect": "4:1"}, "facebook_post": {"width": 1200, "height": 630, "aspect": "1.91:1"}, "facebook_cover": {"width": 820, "height": 312, "aspect": "2.63:1"}, "pinterest_pin": {"width": 1000, "height": 1500, "aspect": "2:3"}, "tiktok": {"width": 1080, "height": 1920, "aspect": "9:16"}, }
• src/fal_mcp_server/handlers/__init__.py:15-15 (registration)

  Export of the handle_resize_image function from image_editing_handlers for use in server.py.
  handle_resize_image,