Deep Dive Into Transformations With the Cloudinary MCP Server

If you’re a developer who lives inside Cursor and already has a Model Context Protocol (MCP) server wired up, you can offload a surprising amount of Cloudinary URL munging to your AI assistant safely and repeatedly. 

You can also watch the YouTube DevHints video of this blog post.

• A Cursor setup that gives your AI agent authoritative context for Cloudinary.
• An MCP toolchain that takes a local image and returns ready-to-paste Cloudinary URLs.
• A repeatable workflow to:
  • Apply the sepia filter.
  • Make a perfect circle thumbnail.
  • And overlay centered text all by prompting.

• Cursor installed.
• An MCP server available in Cursor (the video uses one aliased as “context-7”).
  If you haven’t set up MCP on your machine yet, do that first.
• A Cloudinary account with credentials configured for the MCP server (so the tool can upload/transform).
• A test image is placed in your project root folder (e.g., hero.jpg).

1. Open Cursor > Settings > MCP Servers.
2. Add MCP server (e.g., alias it context-7).
   Exact command/env varies by your server. The key is that Cursor can “Run tool” successfully.

You’ll add two Doc sources so the AI generates the correct Cloudinary syntax:

1. Cloudinary Docs llms.txt:
   
   Think of this like robots.txt, but for LLMs, guidance for how AI should consume the docs.
   • In Cursor > Settings > Indexing & Docs > Add Doc.
   • Paste the Cloudinary Docs LLMs.txt URL.
   • Name it something like cloudinary-docs-llm.
2. Cloudinary transformation rules:
   
   A simple ruleset that nudges the AI toward correct transformation syntax.
   • Add Doc again.
   • Paste the transformation rules URL.
   • Name it cloudinary-transform-rules.

With both added, your agent has the context to produce valid, minimal Cloudinary URLs.

In your Cursor chat, enable:

• Your MCP server (e.g., context-7)
• The two Doc sources you just added:
  • cloudinary-docs-llm
  • cloudinary-transform-rules

Also, mention the image filename you put in your root so the agent knows what to transform.

Prompt example:

Apply a sepia effect to hero.jpg using the Cloudinary URL transformation syntax. Return a single URL I can paste in the browser.

You should get a URL with an e_sepia step (effect = sepia). It will look like this:

https://res.cloudinary.com/<cloud_name>/image/upload/e_sepia/<public_id>.jpgCode language: HTML, XML (xml)

Paste into your browser, and you’ll see the sepia version.

A circle requires a square base. If your original isn’t square, first resize + crop to square, then round the corners.

Prompt example:

Make hero.jpg a perfect circle. If it isn’t square, first make it 400×400, then apply the circle. Return one final URL.

These are what you should expect.

1. Square crop (fill the box so no letterboxing): c_fill,w_400,h_400
2. Circle: r_max

And the combined URL shape:

https://res.cloudinary.com/<cloud_name>/image/upload/c_fill,w_400,h_400/r_max/<public_id>.jpgCode language: HTML, XML (xml)

If you didn’t square it first, you’ll get a rounded rectangle. Ensuring w and h are equal before r_max is the key to a true circle.

Text overlays are a separate “layer” applied over your base transformations.

Prompt example:

Overlay the centered word Pato in green on the circular image. Keep it readable. Return a single URL.

Typical overlay step:

• Text layer: l_text:Arial_64:Pato
• Color: co_rgb:green
• Centering: g_center
• Apply the layer: fl_layer_apply

Full example (chained steps):

https://res.cloudinary.com/<cloud_name>/image/upload

c_fill,w_400,h_400/r_max/

l_text:Arial_64:Pato,co_rgb:green,g_center/fl_layer_apply/

<public_id>.jpgCode language: HTML, XML (xml)

1. Context on
   • Enable context-7, cloudinary-docs-llm, cloudinary-transform-rules.
2. Sepia
   • Prompt example: Add sepia to hero.jpg and return the URL.
     • Result: .../e_sepia/...
3. Circle
   • Prompt example: Make it a perfect circle at 400×400 and return one URL.
     • Result: .../c_fill,w_400,h_400/r_max/...
4. Text overlay
   • Prompt example: Add centered green text Pato, readable size. One final URL.
     • Result: .../l_text:Arial_64:Pato,co_rgb:green,g_center/fl_layer_apply/...

Paste, verify, iterate.

• Rounded rectangle instead of circle.
  • Ensure square geometry before r_max. For example: c_fill,w_400,h_400/r_max.
• Text not showing / wrong color.
  • Keep the overlay parameters together, then fl_layer_apply.
  • Use co_rgb:green (or a hex, e.g., co_rgb:00FF00).
• Weird positioning.
  • Start with g_center, then add small offsets like y_20 or x_-10.
• Spacing/special characters in text.
  • URL‑encode the overlay text (e.g., l_text:Arial_64:Hello%20World).
• Long, brittle URLs.
  • Prefer composing in steps (separate by /) and keep each step focused (resize > shape > overlay).

Cloudinary’s MCP servers offer a comprehensive, developer-friendly way to automate and enhance your visual media handling workflows.

Here are some ideas on what to do next:

• Face-aware crops. Swap g_center for g_auto or g_face in your square step.
• Add borders/shadows. bo_2px_solid_black or subtle e_shadow.
• Chain effects. e_sepia/e_contrast:20 (effects are composable).

That’s it. With an MCP server in Cursor and the right doc context, you can ask for high‑level image goals and get back rock‑solid Cloudinary transformation URLs.

To stay updated with the latest product features, follow Cloudinary on Twitter and explore other sample apps.

Building an app with Cloudinary and need inspiration? Visit your App Gallery, or sign up for a free account to get started building today.