Deprecate top-level import

docs/servers/tools.mdx

@@ -266,8 +266,10 @@ At this time, FastMCP responds only to your tool's return *value*, not its retur
 </Tip>
 
 ```python
-from fastmcp import FastMCP, Image
+from fastmcp import FastMCP
+from fastmcp.utilities.types import Image
 import io
+
 try:
     from PIL import Image as PILImage
 except ImportError:

examples/screenshot.py

@@ -6,7 +6,8 @@ Give Claude a tool to capture and view screenshots.
 
 import io
 
-from fastmcp import FastMCP, Image
+from fastmcp import FastMCP
+from fastmcp.utilities.types import Image
 
 # Create server
 mcp = FastMCP("Screenshot Demo", dependencies=["pyautogui", "Pillow"])

src/fastmcp/__init__.py

@@ -11,20 +11,40 @@ from fastmcp.server.context import Context
 import fastmcp.server
 
 from fastmcp.client import Client
-from fastmcp.utilities.types import Image
 from . import client
 
 __version__ = version("fastmcp")
+
+
+# ensure deprecation warnings are displayed by default
+if settings.deprecation_warnings:
+    warnings.simplefilter("default", DeprecationWarning)
+
+
+def __getattr__(name: str):
+    """
+    Used to deprecate the module-level Image class; can be removed once it is no longer imported to root.
+    """
+    if name == "Image":
+        # Deprecated in 2.8.1
+        if settings.deprecation_warnings:
+            warnings.warn(
+                "The top-level `fastmcp.Image` import is deprecated "
+                "and will be removed in a future version. "
+                "Please use `fastmcp.utilities.types.Image` instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        from fastmcp.utilities.types import Image
+
+        return Image
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
+
+
 __all__ = [
     "FastMCP",
     "Context",
     "client",
     "Client",
     "settings",
-    "Image",
 ]
-
-
-# ensure deprecation warnings are displayedby default
-if settings.deprecation_warnings:
-    warnings.simplefilter("default", DeprecationWarning)

tests/tools/test_tool.py

@@ -2,11 +2,12 @@ import pytest
 from mcp.types import EmbeddedResource, ImageContent, TextContent, TextResourceContents
 from pydantic import AnyUrl, BaseModel
 
-from fastmcp import FastMCP, Image
+from fastmcp import FastMCP
 from fastmcp.client import Client
 from fastmcp.exceptions import ToolError
 from fastmcp.tools.tool import Tool, _convert_to_content
 from fastmcp.utilities.tests import temporary_settings
+from fastmcp.utilities.types import Image
 
 
 class TestToolFromFunction:

tests/tools/test_tool_manager.py

@@ -8,11 +8,12 @@ import pytest
 from mcp.types import ImageContent
 from pydantic import BaseModel
 
-from fastmcp import Context, FastMCP, Image
+from fastmcp import Context, FastMCP
 from fastmcp.exceptions import NotFoundError, ToolError
 from fastmcp.tools import FunctionTool, ToolManager
 from fastmcp.tools.tool import Tool
 from fastmcp.utilities.tests import temporary_settings
+from fastmcp.utilities.types import Image
 
 
 class TestAddTools: