Skip to main content
Glama
kashifamin72

Cloudflare Image MCP

by kashifamin72
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

opencode-cloudflare-image-mcp

An MCP (Model Context Protocol) server that gives any MCP-capable AI model (Claude Desktop, opencode, etc.) the ability to generate images from text prompts and describe images in text, using Cloudflare Workers AI models.

Features

  • generate_image — Generate images from text prompts using Cloudflare text-to-image models (FLUX.1 Schnell, SDXL, DreamShaper, and more).

  • describe_image — Generate text descriptions of images using Cloudflare image-to-text models (LLaVA, Moondream, uForm).

  • list_models — Discover all supported models with aliases and defaults.

  • Generated images are saved to disk; the file path is returned to the model.

  • Image-to-text supports both local file paths and HTTP(S) URLs as input.

Related MCP server: nanobanana-mcp-server

Install via OpenCode Agent

Paste this to your opencode agent to install and configure:

Install the opencode-cloudflare-image-mcp MCP server globally, then add it to my opencode.json config at ~/.config/opencode/opencode.json as a local MCP server with:
- type: local
- command: ["node", "E:/Image-MCP/dist/index.js"] (or your install path)
- environment with CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN

Or manually:

npm install -g opencode-cloudflare-image-mcp

Then add to ~/.config/opencode/opencode.json:

{
  "mcp": {
    "cloudflare-image": {
      "type": "local",
      "command": ["node", "E:/Image-MCP/dist/index.js"],
      "environment": {
        "CLOUDFLARE_ACCOUNT_ID": "your-account-id",
        "CLOUDFLARE_API_TOKEN": "your-api-token"
      },
      "enabled": true
    }
  }
}

Note: Use "environment" not "env" for the env vars in opencode config.

Install (Manual)

npm install -g opencode-cloudflare-image-mcp

Or use directly with npx:

npx opencode-cloudflare-image-mcp

Configuration

Environment Variables

Variable

Required

Default

Purpose

CLOUDFLARE_ACCOUNT_ID

yes

—

Cloudflare account ID

CLOUDFLARE_API_TOKEN

yes

—

Bearer token for API auth

IMAGE_MCP_OUTPUT_DIR

no

./generated-images

Where generated PNG files are saved

IMAGE_MCP_DEFAULT_T2I_MODEL

no

@cf/black-forest-labs/flux-1-schnell

Default text-to-image model

IMAGE_MCP_DEFAULT_I2T_MODEL

no

@cf/llava-hf/llava-1.5-7b-hf

Default image-to-text model

Getting a Cloudflare API Token

  1. Go to the Cloudflare dashboard.

  2. Navigate to My Profile → API Tokens.

  3. Click Create Token.

  4. Use the Workers AI template, or create a custom token with Workers AI:Read permission.

  5. Copy the token and set it as CLOUDFLARE_API_TOKEN.

Your Cloudflare Account ID is visible on the dashboard overview page or any domain's overview page.

Client Configuration

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "cloudflare-image": {
      "command": "npx",
      "args": ["-y", "opencode-cloudflare-image-mcp"],
      "env": {
        "CLOUDFLARE_ACCOUNT_ID": "your-account-id",
        "CLOUDFLARE_API_TOKEN": "your-api-token"
      }
    }
  }
}

opencode / Generic stdio

{
  "mcp": {
    "cloudflare-image": {
      "type": "local",
      "command": ["npx", "-y", "opencode-cloudflare-image-mcp"],
      "env": {
        "CLOUDFLARE_ACCOUNT_ID": "your-account-id",
        "CLOUDFLARE_API_TOKEN": "your-api-token"
      }
    }
  }
}

Usage

Once connected, the AI model can call these tools:

generate_image

Generate an image of a cyberpunk lizard in a neon-lit city

The model will call generate_image with the prompt. The image is saved to disk and the file path is returned.

describe_image

Describe the image at /path/to/image.png

Or with a URL:

What's in this image? https://example.com/photo.jpg

list_models

What image models are available?

Supported Models

Text-to-Image

Alias

Model ID

Default

flux-schnell

@cf/black-forest-labs/flux-1-schnell

yes

flux-2-klein-4b

@cf/black-forest-labs/flux-2-klein-4b

sdxl-lightning

@cf/bytedance/stable-diffusion-xl-lightning

dreamshaper

@cf/lykon/dreamshaper-8-lcm

sdxl-base

@cf/stabilityai/stable-diffusion-xl-base-1.0

Image-to-Text

Alias

Model ID

Default

llava

@cf/llava-hf/llava-1.5-7b-hf

yes

uform

@cf/unum/uform-gen2-qwen-500m

moondream

@cf/moondream/moondream3.1-9B-A2B

Development

pnpm install
pnpm test
pnpm build

License

MIT

Available Tools

3 tools
describe_imageB

Generate a text description of an image using a Cloudflare Workers AI image-to-text model.

ParametersJSON Schema
NameRequiredDescriptionDefault
imageYesLocal file path or HTTP(S) URL of the image to describe
modelNoModel alias or full @cf/... id
promptNoInstruction, e.g. "How many cats are in this image?"
max_tokensNoResponse length cap
temperatureNoSampling temperature

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It only states the basic purpose without disclosing behavioral traits like supported image formats, model availability, potential errors, or that it is a read-only operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no unnecessary words. Efficiently conveys the core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, no annotations, and the description is too sparse. It does not explain the output format, how to choose model, or provide any guidance for a 5-parameter tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so all parameters are documented in the schema. The description adds no additional meaning beyond the schema details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool generates a text description from an image using a specific service (Cloudflare Workers AI). It distinguishes itself from siblings: generate_image (creates images) and list_models (lists available models).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use vs alternatives. The context of siblings implies use for description rather than generation, but no explicit when-not or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_imageB

Generate an image from a text prompt using a Cloudflare Workers AI text-to-image model.

ParametersJSON Schema
NameRequiredDescriptionDefault
seedNoRandom seed for reproducibility
modelNoModel alias (e.g. "flux-schnell") or full "@cf/..." id
stepsNoDiffusion steps
promptYesText prompt for image generation
filenameNoOutput filename
output_dirNoOverride save directory

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description carries the full burden of behavioral disclosure. It mentions the model type but does not disclose other important behaviors such as default model, output format, potential errors (e.g., content moderation), or performance characteristics. This leaves the agent underinformed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that front-loads the core purpose. No redundant words. However, it could incorporate additional concise information (e.g., output type) without losing conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description should ideally mention the return value (e.g., URL or file path). It also does not explain how the 'model' parameter interacts with the sibling tool 'list_models' or provide defaults. For a 6-parameter tool, this minimal description leaves significant gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so each parameter already has a clear schema-level description. The tool description adds no further semantic meaning beyond what is in the schema. Therefore, it meets the baseline of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the verb 'generate', the resource 'image', and the specific mechanism 'from a text prompt using a Cloudflare Workers AI text-to-image model'. This distinguishes it from sibling tools 'describe_image' and 'list_models' which perform different actions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives. The purpose is clear, but there is no mention of prerequisites, limitations, or when not to use it. Sibling tools are different enough that confusion is unlikely, but the lack of guidelines leaves room for improvement.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_modelsA

List supported Cloudflare Workers AI image models.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description implies a safe, read-only operation; no side effects or destructive behavior are suggested, which is appropriate for a list action.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, front-loaded with the verb 'List', no wasted words; perfect conciseness for a simple tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Adequate for a parameterless listing tool, but lacks details on the output structure (e.g., model IDs, names) since no output schema exists; minor gap given simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0 parameters, the baseline is 4; the description adds no parameter info beyond the schema, which is acceptable as there are none to define.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'List supported Cloudflare Workers AI image models' clearly states the action (list) and the resource (supported models), distinguishing it from sibling tools that describe or generate images.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use vs. siblings; the purpose is implied but not formally contrasted, leaving the agent to infer context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv1.0.0
    • First observeddescribe_image
    • First observedgenerate_image
    • First observedlist_models
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.8/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a distinct purpose: describe_image processes an input image, generate_image creates an image from text, and list_models provides model discovery. No overlap or ambiguity.

Naming Consistency5/5

All tool names follow a consistent snake_case verb_noun pattern (describe_image, generate_image, list_models), making them predictable and easy to understand.

Tool Count4/5

With only 3 tools, the server is focused but covers core image operations. While slightly thin, it's appropriate for a specialized image AI server and doesn't feel overcrowded.

Completeness4/5

The server provides generate and describe functionality along with model discovery. Minor gaps exist (e.g., no edit or delete endpoints), but the surface is adequate for basic image generation and description tasks.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers