Developers

Cova MCP 使用手册

工具清单、两大工作流、扣费说明与各客户端配置对照。还没安装？先回 /mcp 复制一键安装命令。

Agent 会自动判断

安装 Cova MCP 后，Agent 在需要音乐时会主动调用，无需你下指令。

你不需要指定走哪条流程。输入再模糊——一个项目文件、一段视频脚本、一句话场景（「给我的产品发布视频配段音乐」）——Agent 都会自行判断：要现成的歌走歌曲匹配，要做新歌走歌曲生成；拿不准时它会先给出一句话方案再动手。
判断依据写在 MCP server 的 initialize instructions 与内置 Skill（cova-music-matching / cova-music-creation）里，支持 Skill 的 Agent 安装后自动获得，无需额外配置。
歌曲匹配的交付物是歌单分享链接：Agent 会把选好的曲目建成歌单并开启分享，把链接发给你。打开链接可逐首试听，登录后一键下载。
涉及扣 co 的操作（生成、下载）Agent 必须先向你报价并征得同意（confirm=true），不会静默扣费。

两大核心工作流

npm 包内置两个 Agent Skill，分别对应两类最常见的需求。安装 MCP 后，支持 Skill 的 Agent 会自动获得完整流程引导。

歌曲匹配

cova-music-matching

从曲库找现成的歌、配乐与 BGM，整理成歌单交付。检索、试听、建歌单、开分享都不扣 co，只有最终下载才扣。

1说需求：场景、情绪、风格。Agent 调用 search_tracks 多角度检索曲库（可匿名）。
2对比候选：用 get_track_preview_url 逐首试听，必要时查 get_library_pricing 计价。
3整理歌单：create_user_playlist 与 add_playlist_item 归档，set_playlist_sharing 生成分享链接。
4交付：访客打开官网链接即可逐首试听；登录后可一键下载（此步才扣 co）。

歌曲生成

cova-music-creation

从零创作一首新歌。写词与定风格不扣 co，确认后才提交生成（一次 2 首，扣 co）。

1写词：generate_lyrics 根据描述生成歌词，可反复迭代（需确认，不扣 co）。
2定风格：generate_style_prompt 生成风格提示词（需确认，不扣 co）。
3生成：generate_music 经你确认后提交，一次产出 2 首并扣 co。
4交付：check_generation_status 轮询进度，完成后给出试听与下载。

能力清单（工具总览）

共 30 个 MCP 工具，按用途分为四组。

匿名 — 无需登录即可调用需登录 — 先完成扫码登录需确认 — 参数 confirm=true，Agent 必须先征得你同意扣 co — 消耗账户 co

目录检索

12 个工具

检索曲目、专辑、音乐人与官方歌单，读取曲库词表与计价。全部为公开数据，匿名即可调用。

search_tracks匿名按关键词与流派/场景/情绪等维度搜曲目，先用 get_library_facets 取合法筛选值
get_track匿名曲目详情
get_track_preview_url匿名曲目试听地址
list_albums匿名专辑列表（按月）
get_album匿名专辑详情与曲目
list_artists匿名音乐人列表
get_artist匿名音乐人详情，可附带其已发布曲目
list_playlists匿名官方歌单列表
get_playlist匿名官方歌单详情
get_library_facets匿名曲库可用筛选维度与取值
get_library_pricing匿名曲库下载与生成计价（co），含 generate_music 默认场景费用
get_library_taxonomy匿名曲库词表（genre/scene/mood 等维度）

账户与歌单

11 个工具

登录态与个人资产：收藏、自建歌单、个人曲库、作品笔记与下载记录。

login匿名发起 device flow 扫码登录
auth_status匿名查看当前登录状态与用户信息
get_me需登录当前用户信息、co 余额与权益
list_favorites需登录收藏的曲目
list_user_playlists需登录自建歌单列表
create_user_playlist需登录新建歌单（配合分享做选曲交付）
set_playlist_sharing需登录开启/关闭歌单公开分享链接
add_playlist_item需登录向自建歌单添加曲目
list_user_library需登录个人曲库
list_notes需登录作品笔记列表
list_downloads需登录下载/购买记录

创作

4 个工具

写词、定风格、提交生成、轮询进度。歌词与风格提示词不扣 co，只有 generate_music 在确认后扣 co。

generate_lyrics需登录需确认根据 prompt 生成歌词
generate_style_prompt需登录需确认根据 prompt 生成风格提示词
generate_music需登录需确认扣 co提交生成，一次产出 2 首；用 check_generation_status 轮询
check_generation_status需登录查询生成任务状态，传 jobId 返回全部作品（2 首）

交易

3 个工具

余额、订单与下载结算。不发起支付，充值请在官网完成。

get_credit_balance需登录co 余额与曲库下载单价
list_orders需登录订单列表
create_download_checkout需登录需确认扣 co按曲目单价 × 未购买数量扣 co，购买曲目下载

扣费说明

只有 generate_music（一次生成 2 首）与 create_download_checkout（购买曲目下载）会扣 co，且都必须经你确认（confirm=true）。
generate_lyrics 与 generate_style_prompt 需确认但不扣 co；检索、试听、建歌单、开分享完全免费。
余额用 get_credit_balance 查询；generate_music 默认场景（带唱、2 首、含封面）的费用与明细用 get_library_pricing 查看（generation.total / generation.items）。
MCP 不开放充值与支付发起；余额不足时 Agent 会引导你前往官网定价页充值。

co 不足时请前往定价页充值。

Server 名称：cova 与 covalink

在 Codex、Claude Code 等客户端里，MCP 的显示名来自你配置里的 server key，而不是 server 上报的名字。因此 /mcp 列表里显示什么，取决于你注册时写的名字。

现在推荐的注册名统一为 cova：claude mcp add cova -- ...、Codex config.toml 的 [mcp_servers.cova]。npm 包名保持 covalink-mcp 不变。

早前已按 covalink 命名安装的无需修改，仅是显示名差异，工具与功能完全一样；server initialize 上报名也保持 covalink 以保证已安装用户的工具前缀不变。

客户端配置对照

一键安装命令已覆盖绝大多数场景；下表是各产品的配置文件路径与对应内容，供手动核对。

也可以把 Agent 安装卡发给你的 AI 助手，由它自动完成配置。

Cursor~/.cursor/mcp.json 或项目 .cursor/mcp.json

~/.cursor/mcp.json 或项目 .cursor/mcp.json

Cursor mcp.json

{
  "mcpServers": {
    "cova": {
      "command": "npx",
      "args": [
        "-y",
        "-p",
        "covalink-mcp",
        "covalink-mcp"
      ]
    }
  }
}

Claude Code~/.claude.json（user）或项目 .mcp.json

~/.claude.json（user）或项目 .mcp.json

Claude Code 命令

claude mcp add --scope user cova -- npx -y -p covalink-mcp covalink-mcp

Claude Code JSON

{
  "mcpServers": {
    "cova": {
      "command": "npx",
      "args": [
        "-y",
        "-p",
        "covalink-mcp",
        "covalink-mcp"
      ]
    }
  }
}

Codex~/.codex/config.toml 或项目 .codex/config.toml

~/.codex/config.toml 或项目 .codex/config.toml

Codex 命令

codex mcp add cova -- npx -y -p covalink-mcp covalink-mcp

Codex config.toml

[mcp_servers.cova]
command = "npx"
args = ["-y", "-p", "covalink-mcp", "covalink-mcp"]

推荐先 npm i -g covalink-mcp，再把 command 直接写成二进制绝对路径（如 /opt/homebrew/bin/covalink-mcp，用 which covalink-mcp 确认），避免 npx 冷启动超时被 Codex 跳过（日志出现 "omitting pending optional MCP server"，工具不注入）。
坚持用 npx 的话，在 config.toml 顶层加 mcp_optional_startup_grace_ms = 20000 并重启桌面端。
服务器开关位置：设置 → 插件 → MCP 标签页，确认 cova 已启用。
改配置后需新开对话：旧线程的工具集不会刷新。

Grok CLI~/.grok/config.toml 或项目 .grok/config.toml

~/.grok/config.toml 或项目 .grok/config.toml

Grok CLI 命令

grok mcp add cova -- npx -y -p covalink-mcp covalink-mcp

Grok config.toml

[mcp_servers.cova]
command = "npx"
args = ["-y", "-p", "covalink-mcp", "covalink-mcp"]

Antigravity~/.gemini/config/mcp_config.json 或项目 .agents/mcp_config.json

~/.gemini/config/mcp_config.json 或项目 .agents/mcp_config.json

Antigravity mcp_config.json

{
  "mcpServers": {
    "cova": {
      "command": "npx",
      "args": [
        "-y",
        "-p",
        "covalink-mcp",
        "covalink-mcp"
      ]
    }
  }
}

WorkBuddy~/.workbuddy/mcp.json 或项目 .workbuddy/mcp.json

~/.workbuddy/mcp.json 或项目 .workbuddy/mcp.json

WorkBuddy mcp.json

{
  "mcpServers": {
    "cova": {
      "command": "npx",
      "args": [
        "-y",
        "-p",
        "covalink-mcp",
        "covalink-mcp"
      ]
    }
  }
}

CodeBuddy~/.codebuddy/.mcp.json；IDE 里 Settings → MCP → Add MCP

~/.codebuddy/.mcp.json；IDE 里 Settings → MCP → Add MCP

CodeBuddy 命令

codebuddy mcp add-json --scope user cova '{"type":"stdio","command":"npx","args":["-y","-p","covalink-mcp","covalink-mcp"]}'

CodeBuddy mcp.json

{
  "mcpServers": {
    "cova": {
      "command": "npx",
      "args": [
        "-y",
        "-p",
        "covalink-mcp",
        "covalink-mcp"
      ]
    }
  }
}

ZCode~/.zcode/cli/config.json（mcp.servers）；也兼容 ~/.agents/mcp.json

~/.zcode/cli/config.json（mcp.servers）；也兼容 ~/.agents/mcp.json

ZCode config.json

{
  "mcp": {
    "servers": {
      "cova": {
        "command": "npx",
        "args": [
          "-y",
          "-p",
          "covalink-mcp",
          "covalink-mcp"
        ]
      }
    }
  }
}

Qoder设置 → MCP → 添加，粘贴 JSON

设置 → MCP → 添加，粘贴 JSON

Qoder mcpServers

{
  "mcpServers": {
    "cova": {
      "command": "npx",
      "args": [
        "-y",
        "-p",
        "covalink-mcp",
        "covalink-mcp"
      ]
    }
  }
}

Trae设置 → MCP → 原始配置；或项目 .trae/mcp.json

设置 → MCP → 原始配置；或项目 .trae/mcp.json

Trae mcp.json

{
  "mcpServers": {
    "cova": {
      "command": "npx",
      "args": [
        "-y",
        "-p",
        "covalink-mcp",
        "covalink-mcp"
      ]
    }
  }
}

豆包技能 / 连接器 → 新建自定义连接器 → 传输 STDIO

技能 / 连接器 → 新建自定义连接器 → 传输 STDIO

豆包 STDIO 对照

{
  "mcpServers": {
    "cova": {
      "command": "npx",
      "args": [
        "-y",
        "-p",
        "covalink-mcp",
        "covalink-mcp"
      ]
    }
  }
}

Kimi Code~/.kimi-code/mcp.json 或项目 .kimi-code/mcp.json

~/.kimi-code/mcp.json 或项目 .kimi-code/mcp.json

Kimi Code mcp.json

{
  "mcpServers": {
    "cova": {
      "command": "npx",
      "args": [
        "-y",
        "-p",
        "covalink-mcp",
        "covalink-mcp"
      ]
    }
  }
}

DeepSeek Harness~/.dsh/profiles/web/cordis.patch.yml；或工作区 .dsh/dshmm/mcp.json

~/.dsh/profiles/web/cordis.patch.yml；或工作区 .dsh/dshmm/mcp.json

DeepSeek Harness patch

- insert:
  - id: mcp-cova
    name: '@deepseek-ai/dsh-mcp-client'
    config:
      serverName: cova
      transport: stdio
      command: npx
      args: ['-y', '-p', 'covalink-mcp', 'covalink-mcp']

OpenCodeopencode.json / ~/.config/opencode/opencode.json

opencode.json / ~/.config/opencode/opencode.json

OpenCode opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "cova": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "-p",
        "covalink-mcp",
        "covalink-mcp"
      ],
      "enabled": true
    }
  }
}

OpenClaw~/.openclaw/openclaw.json → mcp.servers

~/.openclaw/openclaw.json → mcp.servers

OpenClaw 命令

openclaw mcp set cova '{"command":"npx","args":["-y","-p","covalink-mcp","covalink-mcp"]}'

OpenClaw openclaw.json

{
  "mcp": {
    "servers": {
      "cova": {
        "command": "npx",
        "args": [
          "-y",
          "-p",
          "covalink-mcp",
          "covalink-mcp"
        ]
      }
    }
  }
}

Hermes~/.hermes/config.yaml → mcp_servers

~/.hermes/config.yaml → mcp_servers

Hermes 命令

hermes mcp add cova --command npx --args "-y -p covalink-mcp covalink-mcp"

Hermes config.yaml

mcp_servers:
  cova:
    command: "npx"
    args: ["-y", "-p", "covalink-mcp", "covalink-mcp"]

Pi（Oh My Pi / omp）~/.omp/mcp.json 或项目 .omp/mcp.json

~/.omp/mcp.json 或项目 .omp/mcp.json

Pi mcp.json

{
  "mcpServers": {
    "cova": {
      "command": "npx",
      "args": [
        "-y",
        "-p",
        "covalink-mcp",
        "covalink-mcp"
      ]
    }
  }
}

安全与边界

扫码授权：device flow 登录，无需申请 API Key。凭证仅保存在你的电脑（~/.config/covalink/credentials.json，权限 0600），不上传任何第三方。
访问令牌 2 小时有效并自动刷新；刷新令牌 30 天并自动轮换；退出登录（cova logout）即清除本地凭证。
所有扣 co 或生成类操作必须经你确认后才会执行（工具参数 confirm=true），余额不足会明确提示。
服务边界：不开放充值与支付发起、管理后台与内部 Worker 接口。

Agent 安装卡

/mcp 首页的一键安装命令已足够使用；这里是完整的安装卡，覆盖更多客户端的逐一说明。

也可以让 Agent 拉取 /mcp/install 获取同一份说明。

链接串（发给 Agent）

https://covalink.cn/mcp/install
https://covalink.cn/mcp
cursor://anysphere.cursor-deeplink/mcp/install?name=cova&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIi1wIiwiY292YWxpbmstbWNwIiwiY292YWxpbmstbWNwIl19
https://cursor.com/en/install-mcp?name=cova&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIi1wIiwiY292YWxpbmstbWNwIiwiY292YWxpbmstbWNwIl19
vscode:mcp/install?%7B%22name%22%3A%22cova%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22-p%22%2C%22covalink-mcp%22%2C%22covalink-mcp%22%5D%7D

完整安装卡

# Cova MCP 自动安装卡
把本段原样发给任意 AI coding agent。识别自己是哪款产品，写入对应 MCP 配置，最后引导用户扫码登录。

Fetch: https://covalink.cn/mcp/install
Docs: https://covalink.cn/mcp
Name: cova
Package: covalink-mcp（已发布 npm，标准启动方式为 npx）
Env: 默认 https://covalink.cn，不必写 COVALINK_API_BASE
Login: npx -y -p covalink-mcp cova login
Credentials: ~/.config/covalink/credentials.json (0600)

## 配置内容（stdio）
command=`npx`，args=`["-y", "-p", "covalink-mcp", "covalink-mcp"]`。
不要用包名裸跑（`npx -y covalink-mcp` 找不到默认 bin）；必须带 `-p covalink-mcp` 加 bin 名。
用户网络拉包失败时，备选：从源码构建（仓库 packages/covalink-mcp，npm install && npm run build），
command 改为 `node`、args 改为 `["<packages/covalink-mcp/dist/mcp.js 绝对路径>"]`。

## 链接
https://covalink.cn/mcp/install
https://covalink.cn/mcp
cursor://anysphere.cursor-deeplink/mcp/install?name=cova&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIi1wIiwiY292YWxpbmstbWNwIiwiY292YWxpbmstbWNwIl19
https://cursor.com/en/install-mcp?name=cova&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIi1wIiwiY292YWxpbmstbWNwIiwiY292YWxpbmstbWNwIl19
vscode:mcp/install?%7B%22name%22%3A%22cova%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22-p%22%2C%22covalink-mcp%22%2C%22covalink-mcp%22%5D%7D

Cursor / VS Code 可用 deeplink 一键安装；其余产品写入配置文件或执行下方命令。

## 识别自己后执行一条
- Claude Code: `claude mcp add --scope user cova -- npx -y -p covalink-mcp covalink-mcp`
- Codex: `codex mcp add cova -- npx -y -p covalink-mcp covalink-mcp`
- Grok CLI: `grok mcp add cova -- npx -y -p covalink-mcp covalink-mcp`
- CodeBuddy: `codebuddy mcp add-json --scope user cova '{"type":"stdio","command":"npx","args":["-y","-p","covalink-mcp","covalink-mcp"]}'`
- OpenClaw: `openclaw mcp set cova '{"command":"npx","args":["-y","-p","covalink-mcp","covalink-mcp"]}'`
- Hermes: `hermes mcp add cova --command npx --args "-y -p covalink-mcp covalink-mcp"`
- Cursor: 写入 ~/.cursor/mcp.json（下方 JSON）
- Antigravity: 写入 ~/.gemini/config/mcp_config.json
- WorkBuddy: 写入 ~/.workbuddy/mcp.json
- ZCode: 设置 → MCP，或 ~/.zcode/cli/config.json 的 mcp.servers
- Qoder: 设置 → MCP 粘贴 mcpServers
- Trae: 设置 → MCP → 原始配置
- 豆包: 自定义连接器 STDIO，命令 npx，参数 -y -p covalink-mcp covalink-mcp
- Kimi Code: 写入 ~/.kimi-code/mcp.json
- DeepSeek Harness: 按下方 patch 挂 dsh-mcp-client
- OpenCode: 写入 opencode.json 的 mcp.cova（type=local, command 数组）
- Pi / omp: 写入 ~/.omp/mcp.json
- Hermes: 若 CLI 询问 Enable all tools，选 Y；也可只写 yaml

## 通用 mcpServers JSON
{
  "mcpServers": {
    "cova": {
      "command": "npx",
      "args": [
        "-y",
        "-p",
        "covalink-mcp",
        "covalink-mcp"
      ]
    }
  }
}

## Codex / Grok TOML
[mcp_servers.cova]
command = "npx"
args = ["-y", "-p", "covalink-mcp", "covalink-mcp"]

安装后调用 MCP 工具 login，或运行 Login 命令，手机打开 /auth/device 确认。

从源码运行（备选）

网络无法访问 npm 公共源时，可从仓库源码构建。

构建后把 MCP 配置中的 command 改为 node，args 改为 packages/covalink-mcp/dist/mcp.js 的绝对路径。

构建并登录

git clone <covalink 仓库地址>
cd packages/covalink-mcp
npm install
npm run build
node dist/cli.js login

常见问题

为什么在 Codex / Claude Code 里显示的是 covalink 而不是 cova？

客户端里 MCP 的显示名来自你配置里的 server key，不是 server 上报的名字。现在推荐的注册名是 cova（如 claude mcp add cova -- ...、config.toml 的 [mcp_servers.cova]）。早前按 covalink 命名安装的无需修改，仅是显示名差异，工具与功能完全一样。

哪些操作会消耗 co？

只有 generate_music（一次生成 2 首）与 create_download_checkout（购买曲目下载）会扣 co，且都必须经你确认（confirm=true）。generate_lyrics 与 generate_style_prompt 需确认但不扣 co；检索、试听、建歌单、开分享完全免费。余额可用 get_credit_balance 查询；generate_music 默认场景的费用与明细可用 get_library_pricing 查看（generation.total / generation.items）。充值请前往官网定价页。

登录状态会过期吗？

访问令牌有效期 2 小时，工具会在过期后自动刷新，正常情况下无需重新登录。刷新令牌 30 天有效，过期后重新运行 cova login 即可。

如何连接测试环境（staging）？

在 MCP 配置的 env 中加入 COVALINK_API_BASE=https://staging.covalink.cn；CLI 则在命令前加同名环境变量。

如何卸载？

从你的 MCP 客户端配置中删除 cova（或旧名 covalink）条目，并删除本地凭证文件 ~/.config/covalink/credentials.json。npx 缓存可用 npx clear-cache 或手动清理。