Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@AI Watercolor Generator MCP generate a watercolor of a misty mountain lake"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Generate watercolor artwork from a text prompt.
Upload a local JPEG, PNG, or WebP image for editing.
Transform uploaded images into watercolor paintings.
Poll asynchronous tasks until an output is ready.
Use the same account and credits as the REST API and hosted MCP server.
Related MCP server: mclans-image-mcp
Node.js 20 or newer
Account credits for generation and editing
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:
AIWATERCOLOR_API_KEY=YOUR_AIWATERCOLOR_API_KEY \
npx -y @ai-watercolor-generator/mcpThe 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:
[mcp_servers.ai_watercolor_generator]
command = "npx"
args = ["-y", "@ai-watercolor-generator/mcp"]
env_vars = ["AIWATERCOLOR_API_KEY"]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:
{
"mcpServers": {
"ai-watercolor-generator": {
"command": "npx",
"args": ["-y", "@ai-watercolor-generator/mcp"],
"env": {
"AIWATERCOLOR_API_KEY": "YOUR_AIWATERCOLOR_API_KEY"
}
}
}
}See the Cursor MCP documentation.
Use the same stdio configuration in the client's local MCP settings:
{
"mcpServers": {
"ai-watercolor-generator": {
"command": "npx",
"args": ["-y", "@ai-watercolor-generator/mcp"],
"env": {
"AIWATERCOLOR_API_KEY": "YOUR_AIWATERCOLOR_API_KEY"
}
}
}
}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 |
| Submit an asynchronous text-to-watercolor task |
| Upload a local JPEG, PNG, or WebP file up to 10 MiB |
| Submit an asynchronous watercolor edit using uploaded image URLs |
| Read task status, outputs, or failure details |
Call generate_watercolor with a prompt. Optional fields are model, aspect_ratio, resolution, and idempotency_key.
{
"prompt": "A red cottage beside a quiet lake, soft wet-on-wet washes",
"model": "watercolor-lite",
"aspect_ratio": "4:3",
"resolution": "1k"
}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:
{
"file_path": "/absolute/path/to/source-image.png"
}Then pass the returned url to edit_watercolor:
{
"prompt": "Preserve the composition with soft transparent watercolor washes",
"input_images": [
"https://cdn.aiwatercolorgenerator.com/api-inputs/.../upload.png"
],
"model": "watercolor-lite",
"aspect_ratio": "auto",
"resolution": "1k"
}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:
Hosted Streamable HTTP: https://www.aiwatercolorgenerator.com/api/mcp
Local stdio: this npm package
Use 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.
The API key is read from AIWATERCOLOR_API_KEY and is never intentionally logged.
Local images are sent to the hosted upload API when you invoke upload_watercolor_input.
Tool calls consume account credits and are subject to API rate and concurrency limits.
Review file paths and tool calls before approving them in your MCP client.
Report vulnerabilities according to SECURITY.md.
pnpm install
pnpm format:check
pnpm typecheck
pnpm test
pnpm pack --dry-runThe 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.
Transform uploaded images into watercolor artwork as an asynchronous task.
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | watercolor-lite | |
| prompt | Yes | ||
| resolution | No | 1k | |
| aspect_ratio | No | auto | |
| input_images | Yes | ||
| idempotency_key | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries more weight. It does disclose a key behavioral trait—this is an asynchronous task, implying the caller receives a task handle rather than an immediate result. However, it does not describe task lifecycle, failure modes, or how to obtain the final output, so transparency remains partial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action and output. Every phrase carries meaning—'uploaded images', 'watercolor artwork', and 'asynchronous task'—with no filler or unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a task-based tool with six parameters access and no output schema, the description is materially incomplete. It does not explain what the task returns, how to poll for completion using get_watercolor_task, or the role of prompt and other parameters, leaving an agent unable to correctly invoke and follow up on this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description adds almost no parameter meaning. It mentions 'uploaded images' corresponding to input_images, but the required prompt parameter is completely unexplained: an agent does not know what kind of prompt to write. Model, resolution, aspect_ratio, and idempotency_key are also left without any semantic guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Transform'), a clear resource ('uploaded images'), the artistic output ('watercolor artwork'), and the asynchronous execution model. This distinguishes it from siblings like generate_watercolor, which implies creation from scratch rather than editing existing images.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly say when to choose this tool over generate_watercolor, upload_watercolor_input, or get_watercolor_task. The asynchronous mention hints that the result is not immediate volume, but no exclusions or alternatives are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create watercolor artwork from a text prompt as an asynchronous task.
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | watercolor-lite | |
| prompt | Yes | ||
| resolution | No | 1k | |
| aspect_ratio | No | auto | |
| idempotency_key | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. The description does reveal one key behavioral trait: the operation is asynchronous. But it does not disclose what the response contains (e.g., a task ID), how the agent polls for completion, possible failure modes, rate limits, or whether the prompt is sent to an external model. For an async operation with zero annotation coverage, this is a significant transparency gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence with no filler, and the core verb and resource are front-loaded. It is appropriately concise for the small amount of information it conveys, though the same brevity contributes to incompleteness in other dimensions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 5 parameters, no annotations, no output schema, and no parameter descriptions, the description is far too minimal. An agent cannot tell what the tool returns, how to chain it with get_watercolor_task, or how to choose sensible settings for model/resolution/aspect_ratio. The async nature is mentioned but not enough to make the tool safely and correctly invokable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate by explaining parameter meaning. It only clarifies that 'prompt' is a text prompt used to create the artwork. It says nothing about model selection, resolution, aspect_ratio, or idempotency_key semantics. The schema provides enums and defaults, but without descriptions the agent must guess the practical meaning of values like 'nano-banana-pro' or the purpose of the idempotency key.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Create'), a clear resource ('watercolor artwork'), the input ('from a text prompt'), and the execution mode ('asynchronous task'). This clearly distinguishes it from siblings: upload_watercolor_input (input setup), edit_watercolor (modifying existing art), and get_watercolor_task (retrieving results). An agent can identify this as the generation entry point without needing to open the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'asynchronous task' implies a workflow where the agent starts the task and later checks status/results, which is an implied usage guideline. However, the description never names sibling tools or explicitly states when to choose this tool over edit_watercolor or get_watercolor_task, nor does it say 'use get_watercolor_task to poll for completion.' Guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current status, output, or error for a watercolor task.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It explicitly discloses that the tool returns status/output/error and implies a read-only query, but doesn't mention any side effects, polling semantics, or lifecycle behavior beyond 'current'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler. It states the verb, resource, and return fields efficiently, earning its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter retrieval tool, the description covers the return values and read-only nature, but lacks usage context, parameter detail, and relationship to sibling tools. Without annotations or an output schema, an agent would have to infer when and how to call it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description never mentions task_id or explains its meaning/format. The only clue is 'a watercolor task,' which doesn't tell the agent the ID is the one returned by generate_watercolor.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Get' and names the resource ('current status, output, or error for a watercolor task'), making the read/polling purpose unmistakable. It differentiates from sibling actions generate/upload/edit through the retrieval verb, though it doesn't explicitly name alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use or alternative guidance is provided. There is no mention that this should be called after generate_watercolor, nor any exclusion like 'use upload_watercolor_input to provide inputs.' The intended usage is only implied by the word 'task'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload a local JPEG, PNG, or WebP file for watercolor editing.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing side effects and constraints. It only states the action and allowed formats, but does not mention whether the upload is synchronous, what it returns (e.g., a task ID), any authentication or size limits, or whether the file is stored temporarily. This is a significant gap for a tool that presumably creates a server-side resource.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with zero wasted words. It states the action, the object, and the purpose immediately, making it easy to scan. This is appropriately concise for a simple upload tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has only one parameter and no output schema, so the description is nearly complete for initiating an upload. However, it omits any mention of what the tool returns or how the result connects to the sibling tools (e.g., a task ID for get_watercolor_task). Given that get_watercolor_task exists, an agent needs to know that upload returns a task reference to poll, which is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the file_path parameter. It adds the meaning that the parameter is a local path to a JPEG, PNG, or WebP file, which is helpful. However, it does not clarify if the path should be absolute or relative, whether base64 is accepted, or any size constraints, leaving partial ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('upload') and a specific resource ('local JPEG, PNG, or WebP file') with a clear purpose ('for watercolor editing'). This distinguishes it from siblings: generate_watercolor creates new art, edit_watercolor modifies existing, and get_watercolor_task retrieves task status. The action and target are unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus its siblings. The phrase 'for watercolor editing' implies it is a prerequisite for editing, but it does not say 'use this before edit_watercolor' or 'use generate_watercolor instead if you want to create from scratch.' An agent must infer the workflow context from the sibling names, which is not reliable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0edit_watercolorgenerate_watercolorget_watercolor_taskupload_watercolor_inputScored across 4 tools
Each tool has a clearly distinct role: text-to-watercolor generation, input image upload, image-to-watercolor editing, and task status retrieval. There is no overlap or ambiguity between the tools.
All tool names follow a consistent verb_noun snake_case pattern: generate_, upload_, edit_, get_. The domain term 'watercolor' appears in every name, reinforcing a clear and predictable convention.
With only 4 tools, the server is tightly scoped to its purpose. Each tool is necessary for the core workflow of generating or editing watercolor art asynchronously, and none are redundant.
The tool set covers the full lifecycle for both generation paths: create via prompt, upload source, edit, and check status. Minor gaps such as canceling a task or listing all tasks prevent a perfect score, but the core workflows are not blocked.
Generate AI images and videos from any compatible MCP client.
Generate AI images, video, music, and sound effects, and upscale them, from any MCP client.
MCP server for Qwen Image 3 AI image generation
Focused MCP server for OpenAI image/audio generation (v2.0.0). Wraps endpoints via HAPI CLI.
