Ideart Design MCP

简体中文

Open-source MCP server and CLI for AI image and video generation through Ideart. It lets Claude Code, Cursor, Codex, Windsurf, OpenClaw, Hermes Agent, and any MCP-compatible host search prompt inspiration, enhance rough ideas, submit image/video jobs, poll async project artifacts, and optionally use local ComfyUI or OpenAI-compatible image providers.

Ideart stays the orchestration layer: the App owns auth, project scope, credits, model routing, provider configuration, asset storage, and generated artifacts. This MCP adapter exposes that runtime safely to local agent hosts.

What It Does

| Tool | Provider config required | Purpose | | ---------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------- | | search_gallery | No | Search Ideart prompt inspiration by query, category, type, model, and locale. | | get_inspiration | No | Fetch the full prompt and images for a selected inspiration entry. | | enhance_prompt | No | Expand a short idea into a structured image prompt locally. | | list_models | No | Show the public Ideart image/video model catalog; authenticated calls may include project-specific overrides. | | manage_preferences | No | Store local MCP preferences such as style, aspect ratio, provider, and favorites. | | generate_image | Yes | Generate through Ideart App Runtime, OpenAI-compatible image APIs, or local ComfyUI workflows. | | generate_video | Yes | Submit an Ideart video generation task. | | get_tool_task_status | Yes | Poll queued or running Ideart Tool Runtime tasks. | | comfyui_workflow | Local only | Import, view, modify, list, and delete local ComfyUI workflow templates for provider: "comfyui" image generation. |

No API key is needed for inspiration. Read-only prompt inspiration, local prompt enhancement, local preferences, and the public model catalog work against https://ideart.ai. Ideart-hosted image/video generation requires IDEART_API_KEY; image generation can alternatively use OPENAI_API_KEY or local ComfyUI.

Ideart Prompt Library

Ideart includes a public prompt inspiration library for visual creation. The MCP server can search it before generation so agents do not have to start from a blank prompt.

Prompt Library entries may include:

• A reusable full prompt or prompt template.
• Preview images or media URLs.
• Category, modality, model, and locale metadata.
• Scores and sorting signals for relevance, quality, or freshness.
• A stable id or slug that can be passed to get_inspiration.

Use search_gallery to discover matching examples:

Find Ideart prompt inspiration for luxury skincare product photography.

Use get_inspiration when the user picks a result and needs the full prompt, images, and metadata:

Get the full prompt for the second inspiration result and adapt it for a coffee brand.

The prompt library is served by Ideart APIs. It is not bundled into the npm package, so the package stays small and the library can update independently.

Install

One-command setup without installing the package:

npx ideart-ai init cursor
npx ideart-ai init claude
npx ideart-ai init windsurf
npx ideart-ai init vscode
npx ideart-ai init roo

The npm package is ideart-ai, and it exposes the shorter ideart command. After a global install, you can use the short command directly:

npm install -g ideart-ai
ideart init cursor
ideart init claude

Or add this server to your MCP host configuration manually:

{
  "mcpServers": {
    "ideart": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": {
        "IDEART_APP_BASE_URL": "https://ideart.ai",
        "IDEART_API_KEY": "sk_..."
      }
    }
  }
}

For read-only inspiration search, you may omit IDEART_API_KEY:

{
  "mcpServers": {
    "ideart": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": {
        "IDEART_APP_BASE_URL": "https://ideart.ai"
      }
    }
  }
}

Restart your MCP host after changing its configuration.

Standalone CLI

Use the standalone CLI when you want one-shot image generation from a shell or script without opening an MCP host:

export IDEART_API_KEY=sk_...

# No install:
npx ideart-ai gen --prompt "a ceramic coffee dripper product photo" --ratio 1:1
npx ideart-ai gen -p "luxury perfume campaign" -m seedream --json
npx ideart-ai gen -p "poster design" --reference https://example.com/ref.png --no-wait

# After `npm install -g ideart-ai`:
ideart gen --prompt "a ceramic coffee dripper product photo" --ratio 1:1

ideart gen uses Ideart App Runtime only. OpenAI-compatible and ComfyUI provider modes are available through the MCP generate_image tool.

Get An API Key

1. Sign in at https://ideart.ai.
2. Open Settings.
3. Go to API Keys.
4. Click Create Key.
5. Name it, for example Claude MCP or Ideart MCP.
6. Copy the generated sk_... key immediately.

The full key is shown only once. If you lose it, delete that key and create a new one.

Configuration

Environment variables:

export IDEART_APP_BASE_URL=https://ideart.ai
export IDEART_API_KEY=sk_...
export IDEART_LOCALE=en

# Optional image-only providers
export OPENAI_API_KEY=...
export OPENAI_BASE_URL=https://api.openai.com
export OPENAI_MODEL=gpt-image-2
export COMFYUI_URL=http://localhost:8188

Equivalent config file:

{
  "ideartAppBaseUrl": "https://ideart.ai",
  "ideartApiKey": "sk_...",
  "ideartLocale": "en",
  "openaiApiKey": "...",
  "openaiBaseUrl": "https://api.openai.com",
  "openaiModel": "gpt-image-2",
  "comfyuiUrl": "http://localhost:8188",
  "comfyuiDefaultWorkflow": "default"
}

Config path:

~/.config/ideart-design-mcp/config.json

Advanced internal deployments may also provide IDEART_USER_ID, IDEART_PROJECT_ID, and IDEART_CHAT_ID, but normal open-source usage should use only IDEART_APP_BASE_URL and IDEART_API_KEY.

Provider Modes

generate_image supports three provider modes:

• provider: "ideart": default when IDEART_API_KEY is configured. Jobs run in Ideart App Runtime with credits, model policy, project assets, and artifact storage.
• provider: "openai": uses OPENAI_API_KEY, OPENAI_BASE_URL, and OPENAI_MODEL against an OpenAI-compatible /v1/images/generations endpoint. Results are saved locally.
• provider: "comfyui": uses local ComfyUI. Import a workflow JSON first with comfyui_workflow import; results are saved locally.

Video generation and get_tool_task_status are Ideart App Runtime features and require IDEART_API_KEY.

Usage Examples

Search inspiration without an API key:

Find image prompt inspiration for a cyberpunk perfume bottle campaign.

List current image/video models:

What image and video models are available in Ideart?

Generate an image with an API key:

Generate a 1:1 premium product photo of a ceramic coffee dripper on a warm stone countertop.

Generate a video with an API key:

Generate a 5 second vertical video of ocean waves crashing against black volcanic rocks.

Poll async work:

Check the status of tool task <toolTaskId>.

Expected agent workflow:

1. Search inspiration first when the brief is broad or exploratory.
2. Enhance short prompts locally when useful.
3. Submit one generation task.
4. If the task is queued or running, call get_tool_task_status instead of submitting again.
5. Report the exact task id, status, artifact URLs, and App messages returned by the tool.

Runtime Notes

• search_gallery, get_inspiration, list_models, enhance_prompt, and manage_preferences work without an API key.
• generate_image defaults to Ideart App Runtime, but can use provider: "openai" or provider: "comfyui" when configured.
• generate_video submits Ideart Tool Runtime tasks. If a task is queued or running, poll with get_tool_task_status instead of resubmitting.
• The App validates project/chat ownership, credits, model availability, provider policy, and project asset access server-side for Ideart-hosted jobs.
• Local reference file upload to Ideart is intentionally not implemented. Use public URLs or Ideart project assets for Ideart/OpenAI-compatible providers. ComfyUI can read local reference paths when the workflow has LoadImage nodes.
• Model availability is controlled by the Ideart App. Do not hardcode model assumptions in host prompts; call list_models or use App defaults.

Troubleshooting

| Problem | Fix | | ---------------------------------------- | ----------------------------------------------------------------------------------------------------- | | MCP tools are not visible | Restart the host after adding the MCP config. | | Inspiration works but generation fails | Check IDEART_APP_BASE_URL, IDEART_API_KEY, account credits, and whether the key is still active. | | Task is queued or running | Call get_tool_task_status with the returned task id. Do not submit the same prompt again. | | Reference image is a local path | Use ComfyUI with a LoadImage workflow, or upload it to Ideart first and use a URL/project asset. | | ComfyUI is not available | Start ComfyUI, set COMFYUI_URL if not using http://localhost:8188, then import an API-format workflow JSON. | | Model choices are unclear | Call list_models; App configuration is the source of truth. | | The API key was lost after creation | Create a new key in Ideart Settings. Full API keys are only shown once. |

Development

npm install
npm test
npm run typecheck
npm pack --dry-run

Run the local server:

npm run build
node bin/ideart-design-mcp.js

License

MIT. See NOTICE.md for third-party notices.