The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the AI Watercolor Generator listing page.
Create watercolor art from text or transform local images with AI from any MCP client that supports local stdio servers.
This package is the official local MCP server for AI Watercolor Generator. It is a small, open-source client for the production API: generation, storage, credits, rate limits, and task processing remain on the hosted service.
Keep your API key private. Do not commit it to a repository or paste it into an issue.
Run the MCP server through npm without a global installation:
The process communicates over stdio, so it is normally launched by an MCP client rather than used interactively.
Codex CLI, the Codex IDE extension, and the ChatGPT desktop app share MCP configuration on the same Codex host. Add this to ~/.codex/config.toml and provide AIWATERCOLOR_API_KEY in the environment that starts Codex:
Restart the client, then run codex mcp list or use /mcp to verify the connection. See the official Codex MCP documentation.
Add this server to your project .cursor/mcp.json or global MCP configuration:
See the Cursor MCP documentation.
Use the same stdio configuration in the client's local MCP settings:
Restart the client after saving. Claude Desktop may present local MCP servers through its Extensions interface; see Anthropic's local MCP server guide for the current setup flow.
| Tool | Purpose |
|---|---|
generate_watercolor | Submit an asynchronous text-to-watercolor task |
upload_watercolor_input | Upload a local JPEG, PNG, or WebP file up to 10 MiB |
edit_watercolor | Submit an asynchronous watercolor edit using uploaded image URLs |
get_watercolor_task | Read task status, outputs, or failure details |
Call generate_watercolor with a prompt. Optional fields are model, aspect_ratio, resolution, and idempotency_key.
The tool returns a task with status queued or processing. Call get_watercolor_task every 2–5 seconds until the status is succeeded, failed, or canceled.
First call upload_watercolor_input with an explicit local file path:
Then pass the returned url to edit_watercolor:
The upload tool reads only the path explicitly supplied in the tool call. It does not scan directories or expand glob patterns. The image is uploaded to AI Watercolor Generator's trusted storage and is then processed by the hosted API.
The API currently supports watercolor-lite, nano-banana-2, nano-banana-pro, and gpt-image-2. Model, resolution, and operation affect credit cost. Failed or canceled tasks receive the refund defined by the hosted API.
See the API documentation for current models, credit costs, limits, error codes, and schemas.
The official MCP Registry entry is com.aiwatercolorgenerator/watercolor and supports two installation styles:
https://www.aiwatercolorgenerator.com/api/mcpUse the hosted endpoint when your client supports authenticated Streamable HTTP. Use this local package when you need stdio compatibility or want an MCP tool to upload a local image path.
AIWATERCOLOR_API_KEY and is never intentionally logged.upload_watercolor_input.The test suite mocks HTTP requests and includes a real subprocess handshake against the built stdio executable. No production API key is needed for normal development tests.