UGCmind MCP
Allows generating images via OpenAI-compatible image APIs as an alternative to UGCmind-hosted image generation.
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., "@UGCmind MCP Search the gallery for a cyberpunk city street at night"
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.
UGCmind MCP

Open-source MCP server and CLI for AI image and video generation through UGCmind. 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.
UGCmind 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.
Open-source scope
This repository contains the complete local MCP adapter: stdio server, CLI, host setup helpers, MCP tools/resources, optional local providers, tests, and plugin manifests. You can inspect it, run it from source, fork it, and contribute under the MIT License.
It does not contain the hosted UGCmind App backend, user data, provider credentials, billing logic, or private deployment configuration. UGCmind-hosted generation still calls the App API, where authentication, project ownership, credits, model policy, skill grants, and artifact persistence are enforced.
The boundary is intentional:
Claude / Codex / Cursor / other MCP host
│ stdio MCP
▼
ugcmind-mcp (this repo)
├─ public discovery and local helpers
├─ optional OpenAI-compatible / ComfyUI image providers
└─ authenticated UGCmind App Runtime calls
│
▼
auth · projects · credits · models · tasks · assetsSee Architecture, Contributing, Security, and Release process.
Related MCP server: nanobanana-mcp
Quick start
Requirements: Node.js 18 or newer and an MCP-compatible host. Prompt inspiration, capabilities, and the public model catalog do not require an account. UGCmind-hosted generation requires a user API key.
One-command host setup
Published npm releases support:
npx -y ugcmind-mcp@0.3.0 init cursor
npx -y ugcmind-mcp@0.3.0 init claude
npx -y ugcmind-mcp@0.3.0 init windsurf
npx -y ugcmind-mcp@0.3.0 init vscode
npx -y ugcmind-mcp@0.3.0 init rooThis installs a standard stdio MCP entry; it does not install UGCmind into the host itself. Restart the host after setup.
Claude Code
For read-only discovery:
claude mcp add --scope user ugcmind -- npx -y ugcmind-mcp@0.3.0For generation, keep the key in an environment variable and register it in the user-scoped MCP entry:
export UGCMIND_API_KEY=sk_...
claude mcp add --scope user \
-e UGCMIND_API_URL=https://ugcmind.com \
-e UGCMIND_API_KEY="$UGCMIND_API_KEY" \
ugcmind -- npx -y ugcmind-mcp@0.3.0Codex
For read-only discovery:
codex mcp add ugcmind -- npx -y ugcmind-mcp@0.3.0For generation:
export UGCMIND_API_KEY=sk_...
codex mcp add \
--env UGCMIND_API_URL=https://ugcmind.com \
--env UGCMIND_API_KEY="$UGCMIND_API_KEY" \
ugcmind -- npx -y ugcmind-mcp@0.3.0Run from source
Use this path for development or before the first npm release is available:
git clone https://github.com/keenocean/ugcmind-mcp.git
cd ugcmind-mcp
npm ci
npm test
npm run build
node bin/ugcmind-mcp.jsTo attach a source checkout to a host, replace npx -y ugcmind-mcp@0.3.0 in the examples above with node /absolute/path/to/ugcmind-mcp/bin/ugcmind-mcp.js.
What It Does
Tool | Provider config required | Purpose |
| No | Discover the live tool catalog, provider availability, access rules, resource URIs, and async task contract. |
| No | Search UGCmind prompt inspiration by query, category, type, model, and locale. |
| No | Fetch the full prompt and images for a selected inspiration entry. |
| No | Expand a short idea into a structured image prompt locally. |
| No | Show the public UGCmind image/video model catalog; authenticated calls may include project-specific overrides. |
| No | Store local MCP preferences such as style, aspect ratio, provider, and favorites. |
| Yes | Find available UGCmind skills that match the user's requested workflow. |
| Yes | Enable a selected skill and obtain its project-scoped tool grant before execution. |
| Yes | Generate through UGCmind App Runtime, OpenAI-compatible image APIs, or local ComfyUI workflows. |
| Yes | Submit a UGCmind video generation task. |
| Yes | Poll queued or running UGCmind Tool Runtime tasks. |
| Local only | Import, view, modify, list, and delete local ComfyUI workflow templates for |
No API key is needed for inspiration. Read-only prompt inspiration, local prompt enhancement, local preferences, and the public model catalog work against https://ugcmind.com. UGCmind-hosted image/video generation requires UGCMIND_API_KEY; image generation can alternatively use OPENAI_API_KEY or local ComfyUI.
Skill-aware workflows
UGCmind skills remain ordinary, individually installable Agent Skills. They all use this same MCP server; users do not need a second installer, a skill-specific MCP, or a custom invocation protocol.
For skill-driven work, the agent first calls find_skill when discovery is needed, then calls run_skill for the selected skill. run_skill returns a scoped grant/run descriptor, and the MCP client automatically carries that descriptor into the permitted concrete tools. Direct calls to these tools are rejected until the matching skill is active:
Research and assets:
web_fetch,create_file_by_url,search_project_assets,read_project_asset,prepare_reference_asset,search_ugc_actors.Creative production:
visual_design_task,video_generation,music_generation,speech_generation.Documents and media:
transcribe_media,write_free_doc,create_voice_profile.
This preserves the same project ownership, skill grants, billing, task queue, and artifact persistence used by UGCmind itself.
Capability and resource discovery
Third-party agents can inspect the current integration instead of relying on a hardcoded tool list:
Call
ugcmind_capabilitieswithview: "overview","discovery","skills","generation","providers", or"all".Read
ugcmind://capabilitiesfor the full machine-readable catalog.Read
ugcmind://modelsfor the current public or project-aware model catalog.Discover prompt inspiration through
search_galleryandget_inspiration.Discover UGC actors, project assets, and brand assets through the paths returned by
ugcmind_capabilities. These project-aware reads deliberately remain behindrun_skill; the resource layer does not bypass project ownership or skill grants.
Every App-backed asynchronous result exposes the same agent-facing fields while preserving the original App response: taskId and toolTaskId aliases, normalized status, nextAction, statusTool, and statusUrl. Provider-specific values remain available as providerStatus and runtimeNextAction. Agents poll statusTool; users may open statusUrl to inspect the project.
UGCmind Prompt Library
UGCmind 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 UGCmind 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 UGCmind APIs. It is not bundled into the npm package, so the package stays small and the library can update independently.
Installation details
One-command setup without installing the package:
npx ugcmind-mcp init cursor
npx ugcmind-mcp init claude
npx ugcmind-mcp init windsurf
npx ugcmind-mcp init vscode
npx ugcmind-mcp init rooThe npm package is ugcmind-mcp, and it exposes the shorter ugcmind command. After a global install, you can use the short command directly:
npm install -g ugcmind-mcp
ugcmind init cursor
ugcmind init claudeOr add this server to your MCP host configuration manually:
{
"mcpServers": {
"ugcmind": {
"command": "npx",
"args": ["-y", "ugcmind-mcp@0.3.0"],
"env": {
"UGCMIND_API_URL": "https://ugcmind.com",
"UGCMIND_API_KEY": "sk_..."
}
}
}
}For read-only inspiration search, you may omit UGCMIND_API_KEY:
{
"mcpServers": {
"ugcmind": {
"command": "npx",
"args": ["-y", "ugcmind-mcp@0.3.0"],
"env": {
"UGCMIND_API_URL": "https://ugcmind.com"
}
}
}
}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 UGCMIND_API_KEY=sk_...
# No install:
npx ugcmind-mcp gen --prompt "a ceramic coffee dripper product photo" --ratio 1:1
npx ugcmind-mcp gen -p "luxury perfume campaign" -m seedream --json
npx ugcmind-mcp gen -p "poster design" --reference https://example.com/ref.png --no-wait
# After `npm install -g ugcmind-mcp`:
ugcmind gen --prompt "a ceramic coffee dripper product photo" --ratio 1:1ugcmind gen uses UGCmind App Runtime only. OpenAI-compatible and ComfyUI provider modes are available through the MCP generate_image tool.
Get An API Key
Sign in at
https://ugcmind.com.Open
Settings.Go to
API Keys.Click
Create Key.Name it, for example
Claude MCPorUGCmind MCP.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 UGCMIND_API_URL=https://ugcmind.com
export UGCMIND_API_KEY=sk_...
export UGCMIND_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:8188Equivalent config file:
{
"ugcmindApiUrl": "https://ugcmind.com",
"ugcmindApiKey": "sk_...",
"ugcmindLocale": "en",
"openaiApiKey": "...",
"openaiBaseUrl": "https://api.openai.com",
"openaiModel": "gpt-image-2",
"comfyuiUrl": "http://localhost:8188",
"comfyuiDefaultWorkflow": "default"
}Config path:
~/.config/ugcmind-mcp/config.jsonAdvanced internal deployments may also provide UGCMIND_USER_ID, UGCMIND_PROJECT_ID, and UGCMIND_CHAT_ID, but normal open-source usage should use only UGCMIND_API_URL and UGCMIND_API_KEY.
Provider Modes
generate_image supports three provider modes:
provider: "ugcmind": default whenUGCMIND_API_KEYis configured. Jobs run in UGCmind App Runtime with credits, model policy, project assets, and artifact storage.provider: "openai": usesOPENAI_API_KEY,OPENAI_BASE_URL, andOPENAI_MODELagainst an OpenAI-compatible/v1/images/generationsendpoint. Results are saved locally.provider: "comfyui": uses local ComfyUI. Import a workflow JSON first withcomfyui_workflow import; results are saved locally.
Video generation and get_tool_task_status are UGCmind App Runtime features and require UGCMIND_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 UGCmind?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:
Search inspiration first when the brief is broad or exploratory.
Enhance short prompts locally when useful.
Submit one generation task.
If the task is queued or running, call
get_tool_task_statusinstead of submitting again.Report the exact task id, status, artifact URLs, and App messages returned by the tool.
Runtime Notes
ugcmind_capabilities,search_gallery,get_inspiration,list_models,enhance_prompt, andmanage_preferenceswork without an API key.generate_imagedefaults to UGCmind App Runtime, but can useprovider: "openai"orprovider: "comfyui"when configured.generate_videosubmits UGCmind Tool Runtime tasks. If a task is queued or running, poll withget_tool_task_statusinstead of resubmitting.The App validates project/chat ownership, credits, model availability, provider policy, and project asset access server-side for UGCmind-hosted jobs.
Local reference file upload to UGCmind is intentionally not implemented. Use public URLs or UGCmind project assets for UGCmind/OpenAI-compatible providers. ComfyUI can read local reference paths when the workflow has LoadImage nodes.
Model availability is controlled by the UGCmind App. Do not hardcode model assumptions in host prompts; call
list_modelsor 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 |
Task is queued or running | Call |
Reference image is a local path | Use ComfyUI with a LoadImage workflow, or upload it to UGCmind first and use a URL/project asset. |
ComfyUI is not available | Start ComfyUI, set |
Model choices are unclear | Call |
The API key was lost after creation | Create a new key in UGCmind Settings. Full API keys are only shown once. |
Development
npm ci
npm test
npm run typecheck
npm run build
npm pack --dry-runRun the local server:
npm run build
node bin/ugcmind-mcp.jsTests do not require a real UGCmind API key. Live App smoke testing must use a non-production account and sanitized project data. Before opening a pull request, read CONTRIBUTING.md.
Project status and support
Source repository: github.com/keenocean/ugcmind-mcp
Issues and feature requests: GitHub Issues
Changelog: CHANGELOG.md
Roadmap: ROADMAP.md
Security reports: follow SECURITY.md; do not disclose vulnerabilities in a public issue.
If npm returns
E404, that version has not been published yet. Run from source until the release appears in the npm registry.
License
MIT. See LICENSE and NOTICE.md for attribution and third-party notices.
Available Tools
25 toolscomfyui_workflowADestructive
Manage ComfyUI workflow templates: list, view parameters, import from file, modify settings, or delete.
Inputs: action (required), name, input, value, +2 more.
create_file_by_urlA
Materialize a public URL as a current-project asset. Use the returned asset id in later media calls. Call run_skill first. This tool rejects direct calls without the active skill grant/run descriptor.
Inputs: url (required), title, purpose, groupName.
create_voice_profileA
Create a reusable project voice profile from 1-3 authorized project audio samples. Call run_skill first. This tool rejects direct calls without the active skill grant/run descriptor.
Inputs: displayName (required), sampleAssetIds (required), tags, language, +3 more.
enhance_promptARead-only
Transform a simple idea into a professional image generation prompt. Use when the user provides a brief description (e.g., "a cat in a garden") and needs a detailed, high-quality prompt. Combine with gallery inspiration for best results. Free, no API key needed.
Inputs: prompt (required), style.
find_skillARead-only
Find an App-managed skill for the current task. Use this before run_skill when the user intent requires a specialized App skill.
Inputs: intent (required), mode, limit, scope, +3 more.
generate_imageADestructive
Generate an image. Supports UGCmind App Runtime, local ComfyUI workflows, or OpenAI-compatible image APIs. UGCmind remains the default when UGCMIND_API_KEY is configured.
Inputs: prompt (required), size, model, quality, +7 more.
generate_videoADestructive
Generate a video through the UGCmind App Tool Runtime. Video jobs are asynchronous; if queued/running, call get_tool_task_status rather than submitting again.
Inputs: prompt (required), wait, model, duration, +5 more.
get_inspirationARead-only
Get the full prompt, media URLs, model/type metadata, and next-action hints for one UGCmind prompt library entry.
Inputs: imageId (required), locale.
get_tool_task_statusARead-only
Check the latest status and artifacts for a UGCmind Tool Runtime task. Use this after generate_image/generate_video returns queued or running.
Inputs: toolTaskId (required).
list_modelsARead-only
List UGCmind image/video generation model options from the App public model catalog. With UGCMIND_API_KEY, project-specific overrides may also be included.
Inputs: activeOnly.
manage_preferencesA
Read or update user preferences: default style, aspect ratio, model, style notes, and favorite prompts. Call with action "get" at conversation start to load preferences.
Inputs: action (required), index, model, style, +4 more.
music_generationA
Generate a project music asset through the UGCmind Tool Runtime. Call run_skill first. This tool rejects direct calls without the active skill grant/run descriptor. If the result is queued or running, do not submit it again; return the task id and stop the turn.
Inputs: prompt (required), style, title, customMode, +7 more.
prepare_reference_assetA
Create reusable project-scoped reference metadata from existing project assets. Call run_skill first. This tool rejects direct calls without the active skill grant/run descriptor.
Inputs: type, traits, displayName, negativePrompt, +3 more.
read_project_assetARead-only
Read metadata or bounded text content from one current-project asset. Call run_skill first. This tool rejects direct calls without the active skill grant/run descriptor.
Inputs: assetId (required), limit, offset, includeContent.
run_skillA
Run and authorize an App-managed skill before calling its concrete App tools. Call this immediately before the tool that will use the skill.
Inputs: reason (required), name, tool, locale, +5 more.
search_galleryARead-only
Search the UGCmind prompt library for visual inspiration. Results include prompt summaries and image URLs when available; render Markdown images for visual browsing.
Inputs: type, limit, model, query, +5 more.
search_project_assetsARead-only
Search assets owned by the current UGCmind project. Call run_skill first. This tool rejects direct calls without the active skill grant/run descriptor.
Inputs: kind, limit, query, scope, +2 more.
search_ugc_actorsARead-only
Search the approved UGC actor catalog. Materialize a selected public image before using it in generation. Call run_skill first. This tool rejects direct calls without the active skill grant/run descriptor.
Inputs: page, query, gender, region, +3 more.
speech_generationA
Generate a speech audio asset, optionally using an approved voice profile or project reference assets. Call run_skill first. This tool rejects direct calls without the active skill grant/run descriptor. If the result is queued or running, do not submit it again; return the task id and stop the turn.
Inputs: prompt (required), format, file_name, pitch_rate, +8 more.
transcribe_mediaA
Transcribe a project audio or video asset into a persisted transcript asset. Call run_skill first. This tool rejects direct calls without the active skill grant/run descriptor. If the result is queued or running, do not submit it again; return the task id and stop the turn.
Inputs: source_asset_id (required), diarize, quality, keyterms, +5 more.
ugcmind_capabilitiesARead-only
Inspect the live UGCmind MCP tool catalog, provider availability, access rules, discovery paths, and async task contract.
Inputs: view.
video_generationA
Generate a project video asset through the UGCmind Tool Runtime. Call run_skill first. This tool rejects direct calls without the active skill grant/run descriptor. If the result is queued or running, do not submit it again; return the task id and stop the turn.
Inputs: prompt (required), action, assetId, file_name, +4 more.
visual_design_taskA
Generate a project image asset through the UGCmind Tool Runtime. Call run_skill first. This tool rejects direct calls without the active skill grant/run descriptor. If the result is queued or running, do not submit it again; return the task id and stop the turn.
Inputs: prompt (required), assetId, file_name, aspect_ratio, +2 more.
web_fetchA
Fetch a public product or research URL through UGCmind's bounded URL materializer and return its project-safe result. Call run_skill first. This tool rejects direct calls without the active skill grant/run descriptor.
Inputs: url (required), title, purpose.
write_free_docA
Persist a Markdown brief or report as a UGCmind project document asset. Call run_skill first. This tool rejects direct calls without the active skill grant/run descriptor. If the result is queued or running, do not submit it again; return the task id and stop the turn.
Inputs: file_name (required), task, title, markdown, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 25 tools
Multiple tool pairs appear to serve similar purposes—generate_image vs visual_design_task, generate_video vs video_generation, web_fetch vs create_file_by_url, and search_gallery vs get_inspiration—with descriptions not clearly differentiating their boundaries. This creates significant ambiguity for an agent deciding which tool to invoke.
Most tools follow a verb_noun snake_case pattern (e.g., list_models, read_project_asset), but several are noun phrases (video_generation, music_generation, ugcmind_capabilities, comfyui_workflow) and the pair generate_video/video_generation splits the same action across verb-first and noun-first names. The inconsistency is noticeable but not chaotic.
With 25 tools, the set is within the heavy range; while a content-generation server with image, video, audio, and asset management could justify many tools, the presence of redundant pairs suggests some could be consolidated, making the count feel inflated.
The surface covers core workflows: content generation (image/video/speech/music), asset management, prompt library search, model listing, skill management, and task status polling. Minor gaps include lack of update/delete operations for assets and prompts, but these do not critically hinder the primary creation lifecycle.
Maintenance
Related MCP Connectors
Generate AI images and videos from any compatible MCP client.
MCP server for Qwen Image 3 AI image generation
MCP server for Hailuo (MiniMax) AI video generation
MCP server for Wan AI video generation
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceAn MCP server for AI-powered image processing (generate, edit, vary, analyze) supporting OpenAI, Gemini, Ideogram, and custom relay endpoints.-
- AlicenseAqualityDmaintenanceMCP server for AI image generation supporting text-to-image and image-to-image editing via any OpenAI-compatible service, with configurable models, aspect ratios, and sizes.2MIT
- AlicenseAqualityDmaintenanceOpen-source MCP server for AI image and video creation, enabling prompt library search, prompt enhancement, and media generation from Claude Code, Cursor, and other MCP hosts.8MIT
- AlicenseAqualityDmaintenanceAn open-source MCP server that connects AI clients to ImgLume for visual inspiration, prompt improvement, image generation and editing, and video generation.61MIT