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 · assets

See Architecture, Contributing, Security, and Release process.

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 roo

This 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.0

For 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.0

Codex

For read-only discovery:

codex mcp add ugcmind -- npx -y ugcmind-mcp@0.3.0

For 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.0

Run 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.js

To 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
ugcmind_capabilities	No	Discover the live tool catalog, provider availability, access rules, resource URIs, and async task contract.
search_gallery	No	Search UGCmind 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 UGCmind 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.
find_skill	Yes	Find available UGCmind skills that match the user's requested workflow.
run_skill	Yes	Enable a selected skill and obtain its project-scoped tool grant before execution.
generate_image	Yes	Generate through UGCmind App Runtime, OpenAI-compatible image APIs, or local ComfyUI workflows.
generate_video	Yes	Submit a UGCmind video generation task.
get_tool_task_status	Yes	Poll queued or running UGCmind 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://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_capabilities with view: "overview", "discovery", "skills", "generation", "providers", or "all".
• Read ugcmind://capabilities for the full machine-readable catalog.
• Read ugcmind://models for the current public or project-aware model catalog.
• Discover prompt inspiration through search_gallery and get_inspiration.
• Discover UGC actors, project assets, and brand assets through the paths returned by ugcmind_capabilities. These project-aware reads deliberately remain behind run_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 roo

The 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 claude

Or 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:1

ugcmind gen uses UGCmind 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://ugcmind.com.
2. Open Settings.
3. Go to API Keys.
4. Click Create Key.
5. Name it, for example Claude MCP or UGCmind 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 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:8188

Equivalent 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.json

Advanced 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 when UGCMIND_API_KEY is configured. Jobs run in UGCmind 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 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:

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

• ugcmind_capabilities, search_gallery, get_inspiration, list_models, enhance_prompt, and manage_preferences work without an API key.
• generate_image defaults to UGCmind App Runtime, but can use provider: "openai" or provider: "comfyui" when configured.
• generate_video submits UGCmind 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 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_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 UGCMIND_API_URL, UGCMIND_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 UGCmind 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 UGCmind Settings. Full API keys are only shown once.

Development

npm ci
npm test
npm run typecheck
npm run build
npm pack --dry-run

Run the local server:

npm run build
node bin/ugcmind-mcp.js

Tests 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.