Skip to content

Set Up Ark MCP

Set up once, then use Ark from your AI client. The client starts a local Ark server automatically when needed. You do not need ComfyUI, a terminal left open, or a separate server-start command each time.

Your situation Start here
You use a coding agent with terminal and file-editing access Guided local setup
Your team already runs Ark and gave you a server URL Connect to that server, with no local installation
Ark is already installed on your machine Connect your client
You have no setup-capable agent or prefer doing it yourself Manual installation, the technical fallback

Use a coding agent that can run terminal commands and edit files on your machine, such as an appropriately enabled Claude Code, Codex, TRAE IDE, Cursor, VS Code agent, or OpenCode session. Approve only the setup actions you understand. An ordinary chat without those tools cannot install software.

Copy this request into that agent. Replace the client and desired capabilities:

Set up https://github.com/byteplus-sa/ark-mcp for [my client],
user-wide, on this machine. I need [images and video].
Read https://byteplus-sa.github.io/ark-mcp/setup/manual-install/
and my client's integration guide before making changes.
Use the reviewed patched revision, check prerequisites, and ask before
installing missing software. Preserve existing projects and MCP entries.
Resolve paths and prepare the client configuration for me.
Open a private blank credential file in a local non-AI text editor;
I will enter my keys there. Do not read back the populated file
or ask me to paste keys into chat.
Verify with discovery only, without generating, uploading, or spending.
Ask before restarting a client with active jobs. Report any unfinished steps.

This is agent-assisted setup, not a one-click installer. The agent performs the one-time software and configuration steps; you approve changes and enter credentials. If it cannot access the instructions or required tools, stop and use the manual fallback or ask your administrator for help.

For Claude Desktop, run the request in a separate coding agent and name Claude Desktop as the target. Desktop chat alone is not assumed to have installation access.

The ark-mcp-setup skill bundles this workflow for supported agents. To install only those instructions, use the Skills CLI guidance with --skill ark-mcp-setup instead of --skill ark-mcp. Review the bundle and target only your chosen agent. Installing it is separate from authorizing it to prepare the server and MCP connection.

You need a BytePlus account and access to the products you choose. Enter only those keys in the private file the agent prepares, save, then tell it you are done. Never paste keys into chat or client configuration.

What you want Key to obtain
Images, video, image/video/audio understanding ModelArk
Audio generation and speech-to-text Seed Speech
Video enhancement, transcoding, subtitles, audio separation VOD AI MediaKit
Talking avatars Vision AI, plus OmniHuman access

See Provider Keys for where to obtain each key. 3D, Flash and other optional products may have extra account access requirements. Regular Seedance 2.5 4K uses the same model and key, without another flag. You do not need to configure every service.

The credential file is private plaintext, not a secrets vault; software running as your OS user can still read it.

Follow any remaining step in your client guide. Some clients require you to paste the agent-prepared configuration into a settings screen or approve server access.

Then ask your client:

Check the ark-seed connection using only ark_list_models and
ark_job_capabilities. Tell me which services and tools are available.
Do not generate media, run understanding, transcribe, upload, or submit jobs.

Success means the expected tools return discovery results. A green connection indicator alone is not enough. Discovery makes no provider calls and does not prove provider-key validity or account entitlement. If tools are missing, see Troubleshooting.

The ark-mcp skill teaches your agent the server’s workflows, including progress checks and keeping generated results. In a file-capable coding agent, send:

Use the Skills CLI to install only the ark-mcp usage skill from
byteplus-sa/ark-mcp for [my agent], user-wide.
Follow https://byteplus-sa.github.io/ark-mcp/setup/agent-skill/
for the command, prerequisites and verification. Preserve existing skills
and ask before installing missing software or replacing anything.
Do not read credentials, change my MCP connection, or run paid tests.

The CLI handles .agents/skills and .claude/skills locations for supported clients. See Install the Agent Skill for agent selection, project-only installs, and the manual fallback. The skill supplies instructions; it does not install or connect the server.

Continue with Your First Tool Call.

Path resolution, locked dependencies, private-file permissions and the client launch contract are documented once in Manual Installation. They are instructions for your setup agent or administrator, not extra steps after guided setup.

Published v0.3.0 includes the dependency security refresh; the historical v0.2.0 release does not. Follow release selection and check the current release before setup. This unversioned site describes its reviewed main build, not every historical release.