Cloudinary MCP servers and LLM tools (Beta)

Cloudinary provides tools that enable AI agents to apply Cloudinary operations in your product environment and generate code that integrates Cloudinary functionality into your applications. Agents can configure environments, upload assets, manage assets and metadata, apply transformations, perform analysis, and more.

Tools include:

• MCP servers: Local endpoints that expose Cloudinary capabilities to AI agents for performing operations and generating code.
• LLM-friendly docs: Structured references and tools that help language models generate accurate Cloudinary code and workflows.
• Base44 integration: A pre-built integration that you can add when creating apps using Base44 that enables you to incorporate Cloudinary functionality in your no-code apps.

On this page:

• MCP servers
  • Available MCP servers
  • Installation
  • Using with OpenAI Responses API
• LLM-friendly docs
  • Cloudinary in Context7
  • Cloudinary transformation rules
  • Cloudinary docs llms.txt and markdown
• Tips and considerations
• Use cases and examples
• Base44 integration
  • Getting started
  • Video tutorial
  • Supported Cloudinary functionalities
  • Tips
  • Example prompts and apps

Rate this page:

MCP servers

The Cloudinary MCP servers enable you to upload, manage, transform, and analyze your media assets as well as configure your product environment and create structured metadata or use MediaFlows.

Available MCP servers

MCP Server	Description	Add to Cursor
Asset Management	Upload and manage images, videos, and raw files, with support for advanced search and filtering. Easily delete or rename assets and take advantage of folders and tags for better organization.
Environment Config	Manage product environment entities including upload presets, upload mappings, named transformations, webhook notifications, and streaming profiles.
Structured Metadata	Define and manage structured metadata fields, values, and conditional metadata rules.
Analysis	Leverage AI-powered content analysis for automatic tagging, along with tools for content moderation, safety checks, object detection, recognition, and more.
MediaFlows	Create and manage automations in MediaFlows to automate media processing and delivery. For details, refer to the MediaFlows MCP server documentation.

Installation

You can install and run the Cloudinary MCP servers using npm packages.

Make sure you have Node.js (v18 or later) and npm installed before configuring them.

1. Add the MCP server configurations shown below into your LLM client's MCP server settings json file. For more detailed guidance, see our tool-specific instructions.
2. Update your cloud name, API key, and API secret for each server you add. You can find these credentials in the Settings > API Keys page in the Console.

    "cloudinary-asset-mgmt": {
      "command": "npx",
      "args": ["-y", "--package", "@cloudinary/asset-management", "--", "mcp", "start"],
      "env": {
        "CLOUDINARY_CLOUD_NAME": "cloud_name",
        "CLOUDINARY_API_KEY": "api_key",
        "CLOUDINARY_API_SECRET": "api_secret"
      }
    },
    "cloudinary-env-config": {
      "command": "npx",
      "args": ["-y", "--package", "@cloudinary/environment-config", "--", "mcp", "start"],
      "env": {
        "CLOUDINARY_CLOUD_NAME": "cloud_name",
        "CLOUDINARY_API_KEY": "api_key",
        "CLOUDINARY_API_SECRET": "api_secret"
      }
    },
    "cloudinary-smd": {
      "command": "npx",
      "args": ["-y", "--package", "@cloudinary/structured-metadata", "--", "mcp", "start"],
      "env": {
        "CLOUDINARY_CLOUD_NAME": "cloud_name",
        "CLOUDINARY_API_KEY": "api_key",
        "CLOUDINARY_API_SECRET": "api_secret"
      }
    },
    "cloudinary-analysis": {
      "command": "npx",
      "args": ["-y", "--package", "@cloudinary/analysis", "--", "mcp", "start"],
      "env": {
        "CLOUDINARY_CLOUD_NAME": "cloud_name",
        "CLOUDINARY_API_KEY": "api_key",
        "CLOUDINARY_API_SECRET": "api_secret"
      }
    }

Install in Cursor

Install in VSCode

Install in Windsurf

Install in Claude Desktop

Using with OpenAI Responses API

OpenAI's Responses API allows you to integrate MCP servers directly into your OpenAI API calls, enabling AI models to access Cloudinary's MCP server capabilities in real-time.

Here's an example of how to use the OpenAI Responses API to upload an asset to Cloudinary. (Make sure to update the environment credentials with your own.)

const response = await openai.chat.completions.create({
  model: "gpt-4o", 
  messages: [
    {
      role: "user",
      content: "Upload this image and optimize it for web delivery"
    }
  ],
  tools: [
    {
      type: "mcp_server",
      mcp_server: {
        name: "cloudinary-asset-mgmt",
        command: "npx",
        args: ["-y", "--package", "@cloudinary/asset-management", "--", "mcp", "start"],
        env: {
          "CLOUDINARY_CLOUD_NAME": "cloud_name",
          "CLOUDINARY_API_KEY": "api_key",
          "CLOUDINARY_API_SECRET": "api_secret"
        }
      }
    }
  ]
});

LLM-friendly docs

Alongside Cloudinary's MCP servers, we also recommend that you take advantage of the following Cloudinary doc resources to get the optimal results when coding with LLM clients.

Cloudinary in Context7

Context7 is a widely used MCP server for developer documentation code examples (with over 17,000 dev libraries indexed), including Cloudinary docs. It regularly pulls every code example for every SDK from the Cloudinary docs and makes it available to your LLM for reference.

When you use Context7 as part of your Cloudinary-specific LLM prompts, you ensure that your LLM has up-to-date code examples for the latest Cloudinary features and that your LLM client generates more accurate and relevant code for your use-case.

To use Context7 with Cloudinary:

1. Ensure you've added the Context7 MCP to your MCP-supporting LLM client. For instructions, see the Context7 MCP README.
2. When you ask your LLM to write Cloudinary code, append use context7 to the end of your prompt.

Cloudinary transformation rules

cloudinary_transformation_rules.md is a rules-based markdown file that helps LLMs generate syntactically correct, hallucination-free Cloudinary transformations.

Even with all the great content and code examples on the web, LLMs (and even the most experienced Cloudinary developers) sometimes struggle to write syntactically correct transformations, especially for more complex use cases.

By adding this new transformation rules markdown file as doc context for your transformation-related prompts, your LLM client will generally produce more accurate transformations and will only use valid transformation parameters and options that are part of the official Cloudinary documentation.

To use the cloudinary_transformation_rules.md file:

When writing a prompt related to Cloudinary transformations, add the cloudinary_transformation_rules.md file as context for your prompt.

For example, in Cursor:

1. Open your Cursor Settings and select Indexing and Docs.
2. In the Docs section, click Add Doc.
3. Paste the transformation rules URL: https://cloudinary.com/documentation/cloudinary_transformation_rules.md
4. In the form that opens:
   1. Update the doc name to a descriptive name (it defaults to the domain name of 'Cloudinary'). For example, change the name to cld-transformation-rules
   2. Ensure both Prefix and Entrypoint are set to https://cloudinary.com/documentation/cloudinary_transformation_rules.md (the prefix defaults to all of cloudinary.com/documentation).
5. When writing a prompt related to transformations, click the Add context (@) button and select the pre-defined cloudinary-transformation-rules (or the descriptive name you assigned).

Cloudinary docs llms.txt and markdown

In addition to the standard Cloudinary docs website, every Cloudinary doc page is also published as a clean, LLM-friendly markdown page.

These markdown pages enable LLM-based IDEs and chat clients to process and consume content more efficiently. Thus, if you want your LLM client to build code or answer questions based on a specific documentation page (rather than its previously trained data or a general web search), you can provide it the relevant markdown page(s) as context.

To use specific Cloudinary docs markdown pages:

1. Append an *.md extension to any Cloudinary doc page.

   For example, the markdown for this doc page can be found at https://cloudinary.com/documentation/cloudinary_llm_mcp.md

2. Specify the relevant markdown URL as context in your LLM-client.

   If you're working with a chat client that doesn't support remote URLs, download the markdown file and upload it for context with your prompt.

llms.txt

The entire set of Cloudinary doc site markdown files is referenced in a structured llms.txt file.

If your LLM client supports processing llms.txt files, you can pass the Cloudinary docs llms.txt file as context for your Cloudinary-specific prompts.

Tips and considerations

• MCP servers and LLM tools in general aren't always consistent. A prompt or question you write today may yield different results tomorrow.
• Given the option, use the most advanced LLM model available. The better the LLM model, the better your results will be.
• If there are alternative ways to achieve an aim, but you want to use Cloudinary functionality, explicitly tell the LLM to use Cloudinary.
• In some MCP clients, there's no need to reference an MCP server directly in a prompt if the server is enabled.
• When prompting for SDK-based code (e.g., Node, Python), include useContext7 at the end of your prompt for more accurate, context-aware output (see Cloudinary in Context7).
• When asking for transformation logic, include cloudinary_transformation_rules.md as a document context (see Cloudinary transformation rules).
• Enable any required add-ons in the Add-ons section of Console Settings before referencing them in prompts.
• Let the model know whether your cloud uses dynamic or fixed folder structures.
• When managing metadata, mention specific fields or tagging strategies you'd like the tool to manage.

Use cases and examples

Here are some examples prompts that you can use for inspiration:

• "Upload assets from the 'summer_campaign' folder within my project. Auto-tag all the images using the Google auto-tagging add-on."
  Note

  Remember to first register for the add-on.
• "Implement a client-side upload in my app that allows users to upload user-generated content. Use Cloudinary's WebPurify add-on to moderate those assets."
• "Return the URLs of all assets that have the tag 'transparent'."
• "Add the value 'Expired' to the metadata field 'Status' for assets with SKUs '123789', '998y285', and '825168'."
• "Delete all assets tagged with 'campaign-2024'."
• "Create a signed upload preset that allows image uploads, marks access control as 'restricted', and generates eager transformations to size the images for mobile devices."
• "Create a named transformation called 'secure' that places the asset with product ID 'my-company-logo' as a watermark in the center of all assets with 50% opacity."

Base44 integration

Base44 is a no-code automation agent that has a Cloudinary integration with preloaded knowledge of Cloudinary's features and direct access to MCP servers. Use it to quickly create full apps with natural language prompts.

Getting started

Here are the steps to set up and start using the Base44 Cloudinary integration:

1. Go to the Base44 Cloudinary Integration from the integrations catalog.
2. Click Use this integration.
3. Scroll down to fill in your CLOUDINARY_CLOUD_NAME, CLOUDINARY_API_KEY, and CLOUDINARY_API_SECRET in the corresponding fields. You can find these credentials on the API Keys page of the Console Settings.
4. Add your prompt and click on the submit button.

Video tutorial

Watch a short video to help you get started with Cloudinary and Base44. It includes setup instructions along with example apps to inspire your own no-code workflows.

Video Player is loading.

Play Video

Play

Unmute

Current Time 0:00

/

Duration 0:00

Loaded: 0%

Stream Type LIVE

Seek to live, currently behind liveLIVE

Remaining Time -0:00

 

1x

Playback Rate

• 2x
• 1.5x
• 1.25x
• 1x, selected
• 0.5x

Descriptions

• descriptions off, selected

Captions

• captions off, selected

Audio Track

Fullscreen

This is a modal window.

Supported Cloudinary functionalities

Using the Cloudinary Base44 integration, you can create apps that implement the following Cloudinary functionalities:

• Upload an image or video from the local directory or using a remote URL.
• Retrieve asset information.
• Update assets, including tags and metadata, and perform moderation.
• Retrieve assets from a specific folder.
• Search for assets.
• List folders.
• Retrieve metadata fields.
• Retrieve tags.
• Apply transformations to assets.

In addition, you can integrate the following widgets:

• Upload Widget
• Media Library Widget
• Cloudinary Video Player

Tips

• Enable any required add-ons in the Add-ons section of Console Settings before referencing them in your prompt.
• Be explicit that you want to use Cloudinary for a task, even if you've already mentioned it earlier.
• If you want to use a Cloudinary widget, clearly specify this in your prompt and name the widget (e.g., Upload Widget, Media Library Widget).
• Some tasks such as moderating or auto-tagging videos require processing time and may not be available immediately after upload. Your app may need to either wait for a webhook notification or include a follow-up user action (e.g., clicking a refresh button) to display the updated data.
• To use an image or video overlay, the asset must already exist in your product environment. Reference the overlay asset in the prompt using its public ID.
• If errors come up during the generation process, click the prompt to let the AI attempt to resolve them.
• After your app is generated, you can continue refining it by adding additional prompt details.

Example prompts and apps

Below are example prompts and the apps they generated, to give you a sense of what's possible. Keep in mind that MCP servers may not always produce consistent results, and repeating the same prompt can yield different outcomes over time.