You run an MCP server that generates AI images using the Volcano Doubao model and exposes simple, reliable IPC or HTTP-based access for Cursor clients. This server handles image creation with configurable aspect ratios, automatic retries, and clear logging, making it easy to integrate into your Cursor workflows.

How to use

Set up and run the server locally, then connect your Cursor MCP client to request image generation. You can generate images with prompts, choose a save location, and specify an aspect ratio. The server enforces a maximum image size and validates paths and permissions to ensureImages are saved correctly.

How to install

Prerequisites you need before starting:

Install Python 3.10 or newer, Node.js, and the uv package manager. You will also need an API key for the Volcano Doubao image model and Cursor properly installed.

### Prerequisites

- Python 3.10+
- Node.js
- uv (Python package manager) 

### Python environment

```bash
# macOS: install pyenv (optional but recommended)
brew install pyenv

# Install Python version and select it globally (adjust as needed)
pyenv install 3.13.2
pyenv global 3.13.2

Node.js environment

# Install Node.js from the official site or your preferred installer

uv package manager

# macOS
brew install uv

# Or via pip
pip install uv

Volcano Doubao API key

1. Sign in to the Volcano Doubao model service.
2. Create a new API key.
3. Save the key for later use. It will be referenced as ARK_API_KEY in your environment.

Cursor client

Install Cursor IDE and ensure it uses the same Python environment you intend to run the MCP server.

Bring it all together

Once the environment is ready, clone the project and install dependencies as shown in the next section.

## Install and configure the MCP server

Clone the project, install dependencies, configure environment variables, and prepare the server for running.

git clone https://github.com/chenyeju295/mcp_generate_images.git cd mcp_generate_images

Install dependencies

python3 -m pip install fastmcp requests 'volcengine-python-sdk[ark]'

Or install from requirements.txt if provided

pip install -r requirements.txt

Set API key (recommended)

export ARK_API_KEY=your_api_key_here

Verify the key is set

echo $ARK_API_KEY

## Run the server in development mode

Use the following command to start the server with development debugging enabled.

uv run --with fastmcp fastmcp dev /Users/username/Documents/mcp_generate_images/mcp_server.py

## Cursor integration example

Add the MCP server to Cursor by configuring the MCP servers section to run the local uv command directly from Cursor. Use the path to your local mcp\_server.py file.

{ "mcpServers": { "generate_images": { "command": "uv", "args": [ "run", "--with", "fastmcp", "fastmcp", "run", "/Users/chenyeju/Documents/github/mcp_generate_images/mcp_server.py" ] } } }

## Configuration overview

The server configuration includes API access, image generation parameters, and output settings. You can customize the API base URL, the model name, retry behavior, and image output options.

{ "api": { "base_url": "https://ark.cn-beijing.volces.com/api/v3", "model": "doubao-seedream-3-0-t2i-250415", "timeout": 120, "max_retries": 3, "retry_delay": 5 }, "image": { "max_width": 1024, "max_height": 1024, "default_width": 1024, "default_height": 1024, "max_batch_size": 1 }, "output": { "base_folder": "/path/to/save/images", "allowed_extensions": [".png", ".jpg", ".jpeg"], "default_extension": ".png" } }

## Usage guidelines

Key parameters you can pass when requesting an image generation: prompt, file\_name, save\_folder, and aspect\_ratio. The supported aspect ratios are '1:1', '4:3', '16:9', '3:4', and '9:16'. The image size typically does not exceed 1024x1024.

Example usage pattern (pseudo-invocation in your client environment):

generate_image(prompt, file_name, save_folder, aspect_ratio)

```text
prompt: A serene landscape at dawn
file_name: landscape.png
save_folder: /Users/you/images
aspect_ratio: 16:9

Troubleshooting and notes

If you encounter issues, verify that the server is running, the save path is absolute and writable, the API key is valid, and the Python environment is correctly set up. Check network connectivity and that uv is installed.

Common issues and solutions include API timeouts, rate limits, authentication failures, and permission problems writing to the save directory.

Tools and endpoints

The server exposes a single image generation endpoint via the MCP workflow. The key tool is generate_image, which accepts a prompt, target filename, save location, and aspect ratio to produce an image.

Available tools

generate_image

Generates a single image using the provided prompt, saves it to the specified folder with the given file name, and applies the requested aspect ratio.