Fal.ai MCP Server

Instructions

Implementation Reference

• src/fal_mcp_server/handlers/image_handlers.py:102-218 (handler)

  The core handler function that implements the generate_image_structured tool logic. Constructs a structured JSON prompt from the input parameters (scene, subjects, style, etc.) and generates images using the Fal.ai model registry and queue strategy.
  async def handle_generate_image_structured( arguments: Dict[str, Any], registry: ModelRegistry, queue_strategy: QueueStrategy, ) -> List[TextContent]: """Handle the generate_image_structured tool.""" model_input = arguments.get("model", "flux_schnell") try: model_id = await registry.resolve_model_id(model_input) except ValueError as e: return [ TextContent( type="text", text=f"❌ {e}. Use list_models to see available options.", ) ] # Build structured JSON prompt from arguments structured_prompt: Dict[str, Any] = {} # Required field structured_prompt["scene"] = arguments["scene"] # Optional structured fields for field in [ "subjects", "style", "color_palette", "lighting", "mood", "background", "composition", "camera", "effects", ]: if field in arguments: structured_prompt[field] = arguments[field] # Convert structured prompt to JSON string json_prompt = json.dumps(structured_prompt, indent=2) fal_args: Dict[str, Any] = { "prompt": json_prompt, "image_size": arguments.get("image_size", "landscape_16_9"), "num_images": arguments.get("num_images", 1), } # Add optional generation parameters if "negative_prompt" in arguments: fal_args["negative_prompt"] = arguments["negative_prompt"] if "seed" in arguments: fal_args["seed"] = arguments["seed"] if "enable_safety_checker" in arguments: fal_args["enable_safety_checker"] = arguments["enable_safety_checker"] if "output_format" in arguments: fal_args["output_format"] = arguments["output_format"] # Use fast execution with timeout protection logger.info("Starting structured image generation with %s", model_id) try: result = await asyncio.wait_for( queue_strategy.execute_fast(model_id, fal_args), timeout=60, ) except asyncio.TimeoutError: logger.error("Structured image generation timed out for %s", model_id) return [ TextContent( type="text", text=f"❌ Image generation timed out after 60 seconds with {model_id}. Please try again.", ) ] # Check for error in response if "error" in result: error_msg = result.get("error", "Unknown error") logger.error( "Structured image generation failed for %s: %s", model_id, error_msg ) return [ TextContent( type="text", text=f"❌ Image generation failed: {error_msg}", ) ] images = result.get("images", []) if not images: logger.warning( "Structured image generation returned no images. Model: %s", model_id, ) return [ TextContent( type="text", text=f"❌ No images were generated by {model_id}. The prompt may have been filtered or the request format was invalid.", ) ] # Extract URLs safely try: urls = [img["url"] for img in images] except (KeyError, TypeError) as e: logger.error("Malformed image response from %s: %s", model_id, e) return [ TextContent( type="text", text=f"❌ Image generation completed but response was malformed: {e}", ) ] response = ( f"🎨 Generated {len(urls)} image(s) with {model_id} (structured prompt):\n\n" ) for i, url in enumerate(urls, 1): response += f"Image {i}: {url}\n" return [TextContent(type="text", text=response)]
• src/fal_mcp_server/tools/image_tools.py:67-207 (schema)

  The input schema and Tool definition for generate_image_structured, providing detailed structured input parameters for precise image generation control including subjects, camera settings, effects, and more.
  Tool( name="generate_image_structured", description="Generate images with detailed structured prompts for precise control over composition, style, lighting, and subjects. Ideal for AI agents that need fine-grained control.", inputSchema={ "type": "object", "properties": { "scene": { "type": "string", "description": "Overall scene description - the main subject and setting", }, "subjects": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of subject (e.g., 'person', 'building', 'animal')", }, "description": { "type": "string", "description": "Detailed description of the subject", }, "pose": { "type": "string", "description": "Pose or action of the subject", }, "position": { "type": "string", "enum": ["foreground", "midground", "background"], "description": "Position in the composition", }, }, }, "description": "List of subjects with their positions and descriptions", }, "style": { "type": "string", "description": "Art style (e.g., 'Digital art painting', 'Photorealistic', 'Watercolor', 'Oil painting')", }, "color_palette": { "type": "array", "items": {"type": "string"}, "description": "Hex color codes for the palette (e.g., ['#000033', '#6A0DAD', '#FFFFFF'])", }, "lighting": { "type": "string", "description": "Lighting description (e.g., 'Soft golden hour lighting', 'Dramatic chiaroscuro')", }, "mood": { "type": "string", "description": "Emotional mood of the image (e.g., 'Serene', 'Dramatic', 'Mysterious')", }, "background": { "type": "string", "description": "Background description", }, "composition": { "type": "string", "description": "Compositional rules (e.g., 'Rule of thirds', 'Centered', 'Golden ratio')", }, "camera": { "type": "object", "properties": { "angle": { "type": "string", "description": "Camera angle (e.g., 'Low angle', 'Eye level', 'Bird's eye')", }, "distance": { "type": "string", "description": "Shot distance (e.g., 'Close-up', 'Medium shot', 'Wide shot')", }, "focus": { "type": "string", "description": "Focus description (e.g., 'Sharp focus on subject, blurred background')", }, "lens": { "type": "string", "description": "Lens type (e.g., 'Wide-angle', '50mm portrait', 'Telephoto')", }, "f_number": { "type": "string", "description": "Aperture (e.g., 'f/1.8', 'f/5.6', 'f/11')", }, "iso": { "type": "integer", "description": "ISO setting (e.g., 100, 400, 800)", }, }, "description": "Camera settings for photographic style control", }, "effects": { "type": "array", "items": {"type": "string"}, "description": "Visual effects (e.g., ['Bokeh', 'Light rays', 'Lens flare', 'Motion blur'])", }, "negative_prompt": { "type": "string", "description": "What to avoid in the image (e.g., 'blurry, low quality, distorted')", }, "model": { "type": "string", "default": "flux_schnell", "description": "Model ID or alias. Use list_models to see options.", }, "image_size": { "type": "string", "enum": [ "square", "landscape_4_3", "landscape_16_9", "portrait_3_4", "portrait_9_16", ], "default": "landscape_16_9", }, "num_images": { "type": "integer", "default": 1, "minimum": 1, "maximum": 4, }, "seed": { "type": "integer", "description": "Seed for reproducible generation", }, "enable_safety_checker": { "type": "boolean", "default": True, "description": "Enable safety checker to filter inappropriate content", }, "output_format": { "type": "string", "enum": ["jpeg", "png", "webp"], "default": "png", "description": "Output image format", }, }, "required": ["scene"], }, ),
• src/fal_mcp_server/server.py:61-85 (registration)

  Registration of the generate_image_structured handler in the TOOL_HANDLERS dictionary, mapping the tool name to its handler function for execution in the MCP server.
  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/handlers/image_handlers.py:19-22 (registration)

  No, wrong. Wait, this is import in server.py actually. For handlers __init__.py
  arguments: Dict[str, Any], registry: ModelRegistry, queue_strategy: QueueStrategy, ) -> List[TextContent]:
• src/fal_mcp_server/handlers/__init__.py:18-22 (registration)

  Export/import of the handler function in the handlers package __init__.py, making it available for server imports.
  from fal_mcp_server.handlers.image_handlers import ( handle_generate_image, handle_generate_image_from_image, handle_generate_image_structured, )