Fal.ai MCP Server

Instructions

Implementation Reference

• src/fal_mcp_server/handlers/image_editing_handlers.py:189-278 (handler)

  The handler function that implements the core logic for the 'edit_image' tool. It resolves the model, prepares fal_args with image_url and instruction, executes via queue_strategy, handles errors/timeouts, extracts the output URL, and formats the response.
  async def handle_edit_image( arguments: Dict[str, Any], registry: ModelRegistry, queue_strategy: QueueStrategy, ) -> List[TextContent]: """Handle the edit_image tool for natural language image editing.""" model_input = arguments.get("model", "fal-ai/flux-2/edit") 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.", ) ] fal_args: Dict[str, Any] = { "image_urls": [arguments["image_url"]], # Flux 2 Edit expects array "prompt": arguments["instruction"], } # Add optional parameters if "strength" in arguments: fal_args["strength"] = arguments["strength"] if "seed" in arguments: fal_args["seed"] = arguments["seed"] logger.info( "Starting image edit with %s: '%s'", model_id, arguments["instruction"][:50] ) try: result = await asyncio.wait_for( queue_strategy.execute_fast(model_id, fal_args), timeout=90, ) except asyncio.TimeoutError: logger.error("Image edit timed out for %s", model_id) return [ TextContent( type="text", text="❌ Image editing timed out after 90 seconds. Please try again.", ) ] except Exception as e: logger.exception("Image editing failed: %s", e) return [ TextContent( type="text", text=f"❌ Image editing failed: {e}", ) ] # Check for error in response if "error" in result: error_msg = result.get("error", "Unknown error") logger.error("Image editing failed for %s: %s", model_id, error_msg) return [ TextContent( type="text", text=f"❌ Image editing failed: {error_msg}", ) ] # Extract the result image URL - Flux 2 edit returns {"images": [{"url": "..."}]} images = result.get("images", []) if images: output_url = images[0].get("url") if isinstance(images[0], dict) else images[0] else: # Fallback to other common response formats image_data = result.get("image", {}) if isinstance(image_data, dict): output_url = image_data.get("url") else: output_url = result.get("image_url") if not output_url: logger.warning("Image edit returned no image. Result: %s", result) return [ TextContent( type="text", text="❌ Image editing completed but no image was returned.", ) ] response = "✏️ Image edited successfully!\n\n" response += f"**Instruction**: {arguments['instruction']}\n\n" response += f"**Result**: {output_url}" return [TextContent(type="text", text=response)]
• src/fal_mcp_server/tools/image_editing_tools.py:79-112 (schema)

  The Tool schema definition for 'edit_image', including inputSchema with properties like image_url, instruction, model, strength, seed, and required fields.
  Tool( name="edit_image", description="Edit an image using natural language instructions. Describe what changes you want and the AI will apply them.", inputSchema={ "type": "object", "properties": { "image_url": { "type": "string", "description": "URL of the image to edit (use upload_file for local images)", }, "instruction": { "type": "string", "description": "Natural language description of the edit (e.g., 'make the sky more dramatic', 'change the car color to red')", }, "model": { "type": "string", "default": "fal-ai/flux-2/edit", "description": "Editing model. Options: fal-ai/flux-2/edit, fal-ai/flux-2-pro/edit (higher quality)", }, "strength": { "type": "number", "default": 0.75, "minimum": 0.0, "maximum": 1.0, "description": "How much to change the image (0=minimal, 1=maximum)", }, "seed": { "type": "integer", "description": "Seed for reproducible edits", }, }, "required": ["image_url", "instruction"], }, ),
• src/fal_mcp_server/server.py:61-85 (registration)

  The TOOL_HANDLERS dictionary that registers 'edit_image' mapped to handle_edit_image function, used by the call_tool handler to route requests.
  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/server.py:20-39 (registration)

  Import statement in server.py that brings in the handle_edit_image handler for registration in TOOL_HANDLERS.
  from fal_mcp_server.handlers import ( handle_compose_images, handle_edit_image, handle_generate_image, handle_generate_image_from_image, handle_generate_image_structured, handle_generate_music, handle_generate_video, handle_generate_video_from_image, handle_generate_video_from_video, handle_get_pricing, handle_get_usage, handle_inpaint_image, handle_list_models, handle_recommend_model, handle_remove_background, handle_resize_image, handle_upload_file, handle_upscale_image, )