Cloudinary MCP Server - MCP Servers

Content

Manage and transform media assets through Cloudinary's comprehensive cloud-based media platform.

Features

• Upload and store media assets securely
• Apply real-time image and video transformations
• Optimize media for web delivery
• Manage asset metadata and tags
• Generate responsive image variations
• Advanced Cloudinary image and video management with automatic optimization, transformation pipelines, and CDN delivery
• Batch operations support for efficient bulk asset uploads, transformations, and metadata updates with automatic rate limit handling and retry logic
• Real-time asset synchronization capabilities with webhook integration support for monitoring uploads and triggering automated workflows

Use Cases

• Batch optimize images for web
• Dynamic image resizing and cropping
• Video transcoding and optimization
• Asset organization and tagging
• Content moderation and analysis
• Build automated media management workflows that sync external systems with Cloudinary for real-time image and video processing and delivery

Installation

Claude Code

1. claude mcp add cloudinary --env CLOUDINARY_CLOUD_NAME=YOUR_CLOUD_NAME --env CLOUDINARY_API_KEY=YOUR_KEY --env CLOUDINARY_API_SECRET=YOUR_SECRET
2. Verify installation: claude mcp list
3. Test connection: claude mcp status cloudinary

Claude Desktop

1. Get your Cloudinary credentials from https://console.cloudinary.com/
2. Note your Cloud Name, API Key, and API Secret
3. Open Claude Desktop configuration file
4. Add the Cloudinary MCP server configuration with your credentials
5. Restart Claude Desktop

Requirements

• Cloudinary account (free or paid) from https://console.cloudinary.com/
• Cloudinary Cloud Name (found in Cloudinary Console dashboard)
• Cloudinary API Key (found in Cloudinary Console dashboard)
• Cloudinary API Secret (found in Cloudinary Console dashboard)
• Internet connection for accessing Cloudinary MCP server (https://mcp.cloudinary.com/)
• Claude Desktop 0.7.0+ or Claude Code with MCP support
• Rate limit awareness: Admin API limits (Free: 500/hour, Paid: 2000/hour; Upload API has no rate limits)
• Understanding of Cloudinary media transformations, upload presets, and asset management
• File size awareness: Account tier limits (typically 10-100MB per file, use chunked uploads for larger files)
• HTTP transport support (remote MCP server, not local stdio)

Configuration

{
  "cloudinary": {
    "env": {
      "CLOUDINARY_API_KEY": "${CLOUDINARY_API_KEY}",
      "CLOUDINARY_API_SECRET": "${CLOUDINARY_API_SECRET}",
      "CLOUDINARY_CLOUD_NAME": "${CLOUDINARY_CLOUD_NAME}"
    },
    "url": "https://mcp.cloudinary.com/",
    "transport": "http"
  }
}

Examples

Resize all product images to 800x600

Common usage pattern for this MCP server

Ask Claude: "Resize all product images to 800x600"

Apply watermark to videos

Common usage pattern for this MCP server

Ask Claude: "Apply watermark to videos"

Generate responsive image sets

Common usage pattern for this MCP server

Ask Claude: "Generate responsive image sets"

Optimize images for web delivery

Common usage pattern for this MCP server

Ask Claude: "Optimize images for web delivery"

Upload Image with Transformations

Upload an image to Cloudinary with automatic transformations and tagging

// Upload image to Cloudinary with transformations
const result = await cloudinary.uploader.upload("image.jpg", {
  folder: "products",
  transformation: [
    { width: 800, height: 600, crop: "fill" },
    { quality: "auto", fetch_format: "auto" },
  ],
  tags: ["product", "featured"],
});

Security

• OAuth authentication for secure access
• Secure upload presets configuration
• Monitor bandwidth usage
• Set transformation limits
• Cloudinary API keys and secret keys must be securely stored and never exposed in client-side code or public repositories - use environment variables and secure credential management
• Cloudinary signed URLs and upload presets should be used for client-side uploads to prevent unauthorized access and ensure proper authentication
• Cloudinary cloud name and resource identifiers may expose account structure and asset organization - ensure Cloudinary resource IDs are kept private and not shared in public configurations
• Rate limiting and API quota management are critical for Cloudinary MCP servers - implement proper rate limit handling, retry logic, and quota monitoring to prevent service disruption
• Cloudinary webhook configurations and payloads may contain sensitive asset metadata and upload information - ensure webhook endpoints are properly secured with authentication and HTTPS encryption

Troubleshooting

HTTP 420 rate limited error on Admin API requests

Admin API limits: Free plan 500/hour, Paid 2000/hour. Wait for hourly reset or upgrade plan. Use Retry-After header to time your next request. Upload API has no rate limits.

HTTP 401 authentication required error

Verify CLOUDINARY_CLOUD_NAME, API_KEY, and API_SECRET are correctly set. Check signed URLs for add-ons or Strict Transformation mode. Regenerate credentials from Cloudinary Console if authentication fails.

Image transformation fails or returns errors

Verify transformation parameters are valid and supported. Check account tier for transformation quota limits. Ensure URL is properly signed for Strict Transformations mode if enabled.

Upload fails with file too large error

Check file size against your account tier limits (typically 10-100MB). For larger files, use chunked uploads. Verify network connectivity and increase timeout settings for large files.

Cloudinary MCP server authentication errors with API credentials

Verify API key and secret are valid and not expired. Check credentials match the correct cloud name. Ensure credentials are properly configured in environment variables. For signed URLs, verify signature generation is correct.

Cloudinary image upload or transformation failures

Check file size limits (100MB for free tier, 10GB for paid). Verify upload preset permissions allow uploads. Ensure network connectivity is stable. For large files, use chunked upload API with resumable upload support.

Cloudinary MCP server rate limiting or throttling errors

Implement exponential backoff retry logic with jitter. Use Cloudinary API rate limit headers to monitor usage. Reduce concurrent requests. Cache frequently accessed asset URLs. Request rate limit increases from Cloudinary support if needed.

Cloudinary MCP server connection timeouts or network errors

Check network connectivity and firewall settings. Verify Cloudinary API endpoints are accessible. Increase request timeout values. Implement connection pooling and retry mechanisms with exponential backoff.