# opencode-cloudflare-image-mcp

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 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](https://developers.cloudflare.com/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.

## 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:

```bash
npm install -g opencode-cloudflare-image-mcp
```

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

```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)

```bash
npm install -g opencode-cloudflare-image-mcp
```

Or use directly with `npx`:

```bash
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](https://dash.cloudflare.com/).
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`:

```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

```json
{
  "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

```bash
pnpm install
pnpm test
pnpm build
```

## License

MIT