store_media_file

Instructions

Use this tool to store images that can be referenced in flashcard fields using
HTML img tags: <img src="filename">

This is useful when you need to:
- Store an image before creating a note (e.g. to reference it in multiple notes)
- Add an image to an existing card's field

Provide exactly one of url, data, or path:
- path: Absolute path to a local file. PREFERRED when the user shares an image file or screenshot.
- url: A URL to download the image from (e.g. "https://example.com/photo.jpg")
- data: Base64-encoded file content (for small images only)

IMPORTANT: When a user shares an image file or screenshot, prefer using "path" with the absolute
file path. AnkiConnect reads the file directly from disk, which avoids needing to base64-encode
large image files.

Args:
    filename: str - The filename to store the media as (e.g. "diagram.png").
    url: str - Optional URL to download the image from.
    data: str - Optional base64-encoded image data.
    path: str - Optional absolute path to a local file. Preferred for user-shared files.

Implementation Reference

• mcp_ankiconnect/server.py:632-684 (handler)

  The MCP tool handler for store_media_file. Decorated with @mcp.tool() and @handle_anki_connection_error. Accepts filename and one of url/data/path, delegates to the AnkiConnect client, and returns a success/error message.

  @mcp.tool()
  @handle_anki_connection_error
  async def store_media_file(
      filename: str,
      url: str | None = None,
      data: str | None = None,
      path: str | None = None,
  ) -> str:
      """Store an image or media file in Anki's media folder.
  
      Use this tool to store images that can be referenced in flashcard fields using
      HTML img tags: <img src="filename">
  
      This is useful when you need to:
      - Store an image before creating a note (e.g. to reference it in multiple notes)
      - Add an image to an existing card's field
  
      Provide exactly one of url, data, or path:
      - path: Absolute path to a local file. PREFERRED when the user shares an image file or screenshot.
      - url: A URL to download the image from (e.g. "https://example.com/photo.jpg")
      - data: Base64-encoded file content (for small images only)
  
      IMPORTANT: When a user shares an image file or screenshot, prefer using "path" with the absolute
      file path. AnkiConnect reads the file directly from disk, which avoids needing to base64-encode
      large image files.
  
      Args:
          filename: str - The filename to store the media as (e.g. "diagram.png").
          url: str - Optional URL to download the image from.
          data: str - Optional base64-encoded image data.
          path: str - Optional absolute path to a local file. Preferred for user-shared files.
      """
      if not url and not data and not path:
          return "SYSTEM_ERROR: Must provide either 'url', 'data', or 'path' for the media file."
  
      source = "path" if path else ("url" if url else "base64 data")
      async with get_anki_client() as anki:
          logger.info(f"Storing media file '{filename}' via {source}.")
  
          stored_filename = await anki.store_media_file(
              filename=filename,
              url=url,
              data=data,
              path=path,
          )
  
          if stored_filename:
              return (
                  f"Successfully stored media file as '{stored_filename}'. "
                  f'Reference it in card fields with: <img src="{stored_filename}">'
              )
          else:
              return f"SYSTEM_ERROR: Failed to store media file '{filename}'."

• mcp_ankiconnect/server.py:635-663 (schema)

  Input parameters for store_media_file tool: filename (required), url/data/path (optional, exactly one required).

      filename: str,
      url: str | None = None,
      data: str | None = None,
      path: str | None = None,
  ) -> str:
      """Store an image or media file in Anki's media folder.
  
      Use this tool to store images that can be referenced in flashcard fields using
      HTML img tags: <img src="filename">
  
      This is useful when you need to:
      - Store an image before creating a note (e.g. to reference it in multiple notes)
      - Add an image to an existing card's field
  
      Provide exactly one of url, data, or path:
      - path: Absolute path to a local file. PREFERRED when the user shares an image file or screenshot.
      - url: A URL to download the image from (e.g. "https://example.com/photo.jpg")
      - data: Base64-encoded file content (for small images only)
  
      IMPORTANT: When a user shares an image file or screenshot, prefer using "path" with the absolute
      file path. AnkiConnect reads the file directly from disk, which avoids needing to base64-encode
      large image files.
  
      Args:
          filename: str - The filename to store the media as (e.g. "diagram.png").
          url: str - Optional URL to download the image from.
          data: str - Optional base64-encoded image data.
          path: str - Optional absolute path to a local file. Preferred for user-shared files.
      """

• mcp_ankiconnect/server.py:632-634 (registration)

  Registration of store_media_file as an MCP tool via the @mcp.tool() decorator on the FastMCP instance.

  @mcp.tool()
  @handle_anki_connection_error
  async def store_media_file(

• mcp_ankiconnect/ankiconnect_client.py:220-241 (helper)

  The AnkiConnectClient method that sends the storeMediaFile action to the AnkiConnect API. Builds the params dict and invokes via the generic invoke() method.

  async def store_media_file(
      self,
      filename: str,
      data: Optional[str] = None,
      url: Optional[str] = None,
      path: Optional[str] = None,
  ) -> str:
      """Store a media file in Anki's media folder.
  
      Provide exactly one of data, url, or path. If multiple are provided,
      AnkiConnect prioritizes: data > path > url.
  
      Returns the filename as stored by Anki.
      """
      params: dict[str, Any] = {"filename": filename}
      if data is not None:
          params["data"] = data
      if url is not None:
          params["url"] = url
      if path is not None:
          params["path"] = path
      return await self.invoke(AnkiAction.STORE_MEDIA_FILE, **params)

• mcp_ankiconnect/ankiconnect_client.py:53-53 (helper)

  Enum value mapping the 'storeMediaFile' AnkiConnect action string.

  STORE_MEDIA_FILE = "storeMediaFile"