MCP

Connect XinYu AI via MCP

Bring XinYu AI's image, video, audio, and text generation — plus reading and tidying your canvases — into Claude, Cursor, Windsurf, Cline, or any MCP-capable agent. Let your agent generate content directly — on your own account and balance.

Overview

MCP (Model Context Protocol) is the standard for AI agents to call external tools. The XinYu AI MCP server wraps the platform's generation API into a set of typed tools, so your agent can call them with zero custom commands to learn.

Your balance

Same pricing and ledger as the web app — spends your own Xins.

Secure auth

User-level API key — can be read-only, revocable anytime, never exposes provider keys.

31 tools

Image, video, audio, text, editing, jobs, and reading and editing your canvas — all included.

Prerequisites: Node.js 18+ and a XinYu AI account.

Get an API Key

Visit xinyuai.app and sign in to your account.

Open Settings → Developer API Keys

Click your avatar at the top right and choose Settings, then find "Developer API Keys" further down the page.

Create & copy the key

Enter a name for the key and click "Create key". The plaintext key (xys_live_...) is shown only once — copy it immediately. Want a tool that can look things up but never spend Xins? Check "Read-only key (query only, cannot generate)" before creating.

An API key carries your account permissions and can spend your Xins. Keep it secret — never commit it to a repo or share publicly. If leaked, revoke it immediately in the same place.

Install

No manual install needed — the client config below runs it via npx, which fetches the latest version automatically. To install it explicitly:

bash

# No install needed — the client config below runs it via npx.
# To install the command explicitly:
npm install -g @xinyuai/mcp-server
# → exposes the "xinyu-mcp" command

Just continue to the next step and paste the JSON below into your client config.

Configure Your Client

Add the config below to your client's MCP settings, replacing the path and API key.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json

json

{
  "mcpServers": {
    "xinyu": {
      "command": "npx",
      "args": ["-y", "@xinyuai/mcp-server"],
      "env": {
        "XINYU_API_KEY": "xys_live_xxxxxxxxxxxxxxxx",
        "XINYU_BASE_URL": "https://xinyuai.app"
      }
    }
  }
}

Cursor / Windsurf / Cline

Same shape (e.g. Cursor's .cursor/mcp.json):

json

{
  "mcpServers": {
    "xinyu": {
      "command": "npx",
      "args": ["-y", "@xinyuai/mcp-server"],
      "env": { "XINYU_API_KEY": "xys_live_xxxx" }
    }
  }
}

XINYU_BASE_URL already defaults to https://xinyuai.app, so you normally don't need to set it. Restart your client after configuring — the xinyu_* tools will appear.

Available Tools

Generate

xinyu_generate_imageText-to-image / image-to-image, with reference images and several images per call (Nano Banana / GPT Image / SeeDream / Grok Imagine / Wan and more)

xinyu_generate_videoText-to-video / image-to-video / reference-to-video, with start & end frames and reference images, video and audio (Kling / Seedance / Wan / Grok / MiniMax / HappyHorse and more); Seedance 2.5 can render a draft first with draft: true

xinyu_generate_video_finalRender the 1080p final of a Seedance 2.5 draft (pass the draft's jobId; billed as a 1080p render)

xinyu_generate_audioText-to-speech (ElevenLabs), or Seed Audio for speech / music / sound effects from a prompt, with up to 3 reference clips to clone a timbre

xinyu_generate_textText LLM, optionally with images / video as visual context (Gemini / Claude / DeepSeek / GLM / Qwen); returns synchronously, no polling

Edit & enhance

xinyu_image_editEdit an image with a text instruction (redraw or erase)

xinyu_video_editEdit a video with a text instruction (Kling O3 video-to-video; source at least 720px tall)

xinyu_video_actionUpscale or extend a Grok video you generated earlier (needs the original task id)

xinyu_enhanceUpscale and enhance an image (Topaz), with optional face enhancement

xinyu_remove_bgRemove the background, returns a transparent PNG

xinyu_outpaintOutpaint: expand the image up / right / down / left by a number of pixels

Jobs

xinyu_get_jobGet one job's status and assets

xinyu_wait_for_jobWait in one call until a job finishes and return its assets — the way to recover a job after a wait timeout; never re-generate

xinyu_list_jobsList recent jobs, filterable by status and canvas (lost a jobId? use status: RUNNING)

Account & models

xinyu_balanceGet your Xins balance

xinyu_list_modelsList available models and their capabilities (filter by output type) — the authority for model ids

xinyu_estimate_pricePrice an image generation before running it (images only): it uses the very function that bills, so the quote is what you pay

Projects & files

xinyu_list_projectsList my projects (canvases) to get a project_id

xinyu_create_projectCreate a new empty canvas, returns project_id

xinyu_uploadUpload a local image / video / audio file to get a URL usable for generation, optionally placing it on the canvas too

xinyu_list_assetsSearch and list the images, videos and audio already on a canvas, with URLs you can reuse directly (check here before uploading)

Read the canvas

xinyu_read_canvasCanvas overview: node and edge totals plus counts per type and status — safe on a canvas of any size

xinyu_find_nodesSearch a canvas's nodes by title and full prompt, type, status, group or position; always reports the true total

xinyu_inspect_nodesRead full detail for up to 8 nodes: prompt, parameters, position and edges

xinyu_read_node_promptRead a node's full prompt in windows (for very long prompts)

Edit the canvas

xinyu_arrange_canvasTidy the canvas: grid-pack loose content nodes (groups and notes stay put)

xinyu_rename_nodeSet a node's title — nothing else changes: prompt, references, params and result stay (personal canvases only)

xinyu_update_node_paramsChange a node's generation parameters in place (model, ratio, resolution, duration…) — saves a draft only: no regeneration, no Xins spent (personal canvases only)

xinyu_connect_nodesDraw a reference edge between two nodes — the source becomes a reference input of the target (personal canvases only)

xinyu_disconnect_nodesRemove a reference edge; the remaining references shift position, and @image N tokens are positional (personal canvases only)

xinyu_delete_nodesDelete nodes and their edges — irreversible; nodes with a finished (paid) result or still generating need explicit confirmation (personal canvases only)

Generation tools wait for the job to finish and return the asset URL(s) by default (pass wait: false to get the jobId immediately). The default maximum wait is 300s for images, audio and the like and 2400s for video tools; change it with wait_timeout_s, up to 3600s. A timeout is not a failure — the job keeps running server-side; fetch the result with xinyu_wait_for_job (or xinyu_get_job) and never re-generate.

Results of image / video / audio tools (including edit, upscale, background removal and outpaint) must belong to a canvas: project_id is required. Use xinyu_list_projects to find an existing project or xinyu_create_project to make one, then pass its project_id. Results land on that canvas as a node by default (place_on_canvas defaults to true; optional canvas_x / canvas_y for position), visible next time the canvas is opened/refreshed. If the user hasn't chosen a canvas yet, ask whether to create a new one or use an existing canvas first. The text tool xinyu_generate_text does not need a project_id.

Generation tools accept URLs only — never a local path or base64. For a local file, run xinyu_upload first to get a URL; for an asset already on the canvas, find it with xinyu_list_assets and reuse it instead of uploading again.

Start Using

Once configured, just talk to your agent in natural language, e.g.:

💬 "Use nano-banana-2 to generate a cyberpunk city, 2K, 16:9."

💬 "Make a 5-second ocean-wave video with Seedance 2.0."

💬 "Check how many Xins I have left."

💬 "Find every image with 'seaside' in my 'Summer Poster' canvas, then tidy the layout."

The agent automatically picks xinyu_generate_image / xinyu_generate_video / xinyu_balance (or xinyu_find_nodes / xinyu_arrange_canvas for finding and tidying canvas content), waits for completion, and returns the result.