URL Fetch MCP

Instructions

This tool allows Claude to retrieve images from any accessible web URL.
The image is returned in a format that Claude can display.

Implementation Reference

• src/url_fetch_mcp/main.py:64-111 (handler)

  The core handler function for the 'fetch_image' tool. It fetches the image using httpx, validates the content-type, base64-encodes the image data, and returns it in a format compatible with MCP image types.

  @app.tool()
  async def fetch_image(
      url: Annotated[AnyUrl, Field(description="The URL to fetch the image from")],
      timeout: Annotated[int, Field(description="Request timeout in seconds")] = 10,
      ctx: Context = None,
  ) -> Union[str, Dict[str, Any]]:
      """Fetch an image from a URL and return it as an image.
      
      This tool allows Claude to retrieve images from any accessible web URL.
      The image is returned in a format that Claude can display.
      """
      if ctx:
          await ctx.info(f"Fetching image from URL: {url}")
      
      request_headers = {
          "User-Agent": "URL-Fetch-MCP/0.1.0",
      }
      
      async with httpx.AsyncClient(follow_redirects=True, timeout=timeout) as client:
          try:
              response = await client.get(str(url), headers=request_headers)
              response.raise_for_status()
              
              content_type = response.headers.get("content-type", "")
              
              if not content_type.startswith("image/"):
                  error_message = f"URL did not return an image (content-type: {content_type})"
                  if ctx:
                      await ctx.error(error_message)
                  return error_message
              
              image_data = base64.b64encode(response.content).decode("utf-8")
              
              if ctx:
                  await ctx.info(f"Successfully fetched image ({len(response.content)} bytes, type: {content_type})")
              
              # Return image directly - FastMCP handles conversion to MCP types
              return {
                  "type": "image",
                  "data": image_data,
                  "mimeType": content_type
              }
          
          except Exception as e:
              error_message = f"Error fetching image from URL {url}: {str(e)}"
              if ctx:
                  await ctx.error(error_message)
              return error_message

• src/url_fetch_mcp/main.py:65-69 (schema)

  Input schema defined via Annotated types and Field descriptions for URL (AnyUrl) and timeout (int, default 10). Output is Union[str, Dict[str, Any]] for success/error or image data.

  async def fetch_image(
      url: Annotated[AnyUrl, Field(description="The URL to fetch the image from")],
      timeout: Annotated[int, Field(description="Request timeout in seconds")] = 10,
      ctx: Context = None,
  ) -> Union[str, Dict[str, Any]]:

• src/url_fetch_mcp/main.py:64-64 (registration)

  The tool is registered using the @app.tool() decorator on the FastMCP instance.

  @app.tool()