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.
Choose Your Path
Section titled “Choose Your Path”| 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 |
Guided Local Setup
Section titled “Guided Local Setup”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.
1. Ask Your Agent
Section titled “1. Ask Your Agent”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 beforeinstalling 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 fileor 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.
2. Enter Your Keys Privately
Section titled “2. Enter Your Keys Privately”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.
3. Enable and Verify
Section titled “3. Enable and Verify”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 andark_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.
4. Add the Usage Skill (Optional)
Section titled “4. Add the Usage Skill (Optional)”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 frombyteplus-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 skillsand 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.
Technical Details
Section titled “Technical Details”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.