---
title: MCP
description: >-
  远程 MCP 地址为 https://api.linkdash.dev/mcp。可在 Claude、ChatGPT、Cursor 和 Codex 中通过
  OAuth 登录，也可以使用 API 密钥。
sidebar:
  label: MCP
  order: 5
---
远程 MCP 地址为 `https://api.linkdash.dev/mcp`。在客户端中添加该 URL，然后用你的 Linkdash 账号登录。如果智能体运行时没有人在浏览器前操作，请改用 [API 密钥](#automation-and-headless-agents)。纯 Markdown 版本：[mcp.md](https://linkdash.dev/mcp.md)。

## 连接

只需向客户端提供 URL `https://api.linkdash.dev/mcp`。客户端会打开 Linkdash 登录页，然后显示授权确认页面，上面会写明应用名称和授权后返回的站点。点击允许后，客户端就会获得一个用于访问你账号的令牌。

- **claude.ai 和 Claude Desktop：**打开[连接器目录中的 Linkdash](https://claude.ai/directory/linkdash)（或进入 Customize → Connectors 搜索 Linkdash），然后点击 **Connect**。
- **ChatGPT：**ChatGPT 插件目录中的 Linkdash 条目即将上线。在此之前，请在 [Plugins](https://chatgpt.com/plugins) 中选择 **+** → **Add custom MCP server**，输入上面的 URL，并选择 OAuth。
- **Claude Code：**运行 `claude mcp add --transport http linkdash https://api.linkdash.dev/mcp`，然后运行 `claude mcp login linkdash`（或在会话中使用 `/mcp`）。
- **Cursor：**点击 [Add to Cursor](https://cursor.com/install-mcp?name=linkdash&config=eyJ1cmwiOiJodHRwczovL2FwaS5saW5rZGFzaC5kZXYvbWNwIn0%3D) 即可一键安装，然后在 Cursor 提示时登录。也可以在 `mcp.json` 中添加该服务器，只填写 `"url"`，不填写 `headers`。
- **Codex：**运行 `codex mcp add linkdash --url https://api.linkdash.dev/mcp`，然后运行 `codex mcp login linkdash`。

应用获得的访问权限与 API 密钥相同。已连接的应用会列在 [控制台 → API 密钥](https://linkdash.dev/dashboard/keys) 中，点击 **断开连接** 会立即撤销其访问权限。

## 自动化与无界面智能体

登录需要有人在浏览器前操作。对于 CI 任务、定时运行的智能体、服务器以及直接调用 MCP 的代码，请改为发送 [API 密钥](https://linkdash.dev/dashboard/keys)：`Authorization: Bearer ldash_...`。这些密钥与 [HTTP API](/zh/api) 使用的密钥相同。

**Cursor**（`~/.cursor/mcp.json` 或 `.cursor/mcp.json`）：

```json
{
  "mcpServers": {
    "linkdash": {
      "url": "https://api.linkdash.dev/mcp",
      "headers": { "Authorization": "Bearer ${env:LINKDASH_API_KEY}" }
    }
  }
}
```

**Claude Code：**`claude mcp add --transport http linkdash https://api.linkdash.dev/mcp --header "Authorization: Bearer $LINKDASH_API_KEY"`（使用 JSON 配置时需要 `"type": "http"`）。

**Codex：**`codex mcp add linkdash --url https://api.linkdash.dev/mcp --bearer-token-env-var LINKDASH_API_KEY`

**OpenCode：**`opencode mcp add linkdash --url https://api.linkdash.dev/mcp --header Authorization="Bearer $LINKDASH_API_KEY"`

本地开发：使用 Convex 的 `.site` URL 加上 `/mcp`。

## 文件

不要通过 MCP JSON 发送文件字节。应先生成一个上传 URL（`{uploadUrl,storageId}`），由宿主环境通过 PUT 上传文件，然后再创建链接：

```bash
curl https://api.linkdash.dev/v1/uploads \
  -H "Authorization: Bearer ldash_..." \
  -H "Content-Type: application/json" \
  -d '{"fileSize":12345}'

curl -X PUT -H "Content-Type: video/mp4" --data-binary @clip.mp4 "$uploadUrl"

curl https://api.linkdash.dev/v1/links \
  -H "Authorization: Bearer ldash_..." \
  -H "Content-Type: application/json" \
  -d '{"storageId":"…","fileName":"clip.mp4","fileType":"video/mp4","fileSize":12345}'
```

MCP 工具的流程：`files_upload_url` 返回 `{uploadUrl,storageId}` → 宿主环境 PUT 到 `uploadUrl` → 使用该 `storageId` 调用 `links_create`。可选的链接预览卡片字段：`previewName`、`previewDescription`、`previewImageStorageId`（图片按同样方式上传）。可选的 `maxOpenings` 会在打开次数达到该值后暂停链接；`links_update` 可以调高该值，或传入 `clearMaxOpenings`。不要把 `uploadUrl` 展示给用户。

## 工具

| CLI | HTTP | MCP |
| --- | --- | --- |
| `auth whoami` | `GET /me` | `whoami` |
| `links list` | `GET /links`（`?q=&tag=&kind=&status=&folder=&limit=&cursor=`） | `links_list` |
| `links get <id>` | `GET /links/:id`（`?domain=`） | `links_get` |
| `links create --url/--file/--text/--folder` | `POST /links` | `links_create` |
| `links update <id>` | `PATCH /links/:id` | `links_update` |
| `links move <id>` | `POST /links/:id/move` | `links_move` |
| `links copy <id>` | `POST /links/:id/copy` | `links_copy` |
| `links delete <id>` | `DELETE /links/:id`（`?contents=keep\|delete`） | `links_delete` |
| `links share <id> --email <e>` | `POST /links/:id/shares` | `links_share` |
| `links unshare <id> --email <e>` | `DELETE /links/:id/shares/:email` | `links_unshare` |
| `links shares <id>` | `GET /links/:id/shares` | `links_shares` |
| `links shares`（不带 id） | `GET /shares` | `links_shares`（不带 `id`） |
| `links shared` | `GET /shared` | `links_shared` |
| `links leave <_id \| share URL>` | `DELETE /shared/:id` | `links_leave` |
| `links_share_role` | `{ id, email, role }` → `{ id, email, role }`（viewer 或 editor） |
| `links_unlock` | `{ id, variant?, password?, variantPassword? }` → 目标内容；为编辑者解锁受密码保护的变体，有效期 30 分钟 |
| `links_activity` | `{ id, limit?, cursor? }` → `{ items: [{ action, detail?, actor, _creationTime }], cursor }` |
| `links role <id> --email <e> --role viewer\|editor` | `PATCH /links/:id/shares/:email` | `links_share_role` |
| `links unlock <_id \| share URL>` | `POST /links/:id/unlock` | `links_unlock` |
| `links activity <id>` | `GET /links/:id/activity` | `links_activity` |
| `links reset-link <id>` | `POST /links/:id/reset-link` | `links_update`（`resetShareLink: true`） |
| `links stats --last 24h` | `GET /links/:id/stats?last=24h` | `links_stats` |
| `links export` | `GET /links/export` | `links_export` |
| `links import` | `POST /links/import` | `links_import` |
| `links variants list <id>` | `GET /links/:id/variants` | `variants_list` |
| `links variants add <id>` | `POST /links/:id/variants` | `variants_add` |
| `links variants update <id> <name>` | `PATCH /links/:id/variants/:name` | `variants_update` |
| `links variants remove <id> <name>` | `DELETE /links/:id/variants/:name` | `variants_remove` |
| （生成 URL 后由宿主环境 PUT） | `POST /uploads` | `files_upload_url` |
| | `DELETE /uploads/:storageId` | `files_discard` |
| `webhooks list/create/get/rotate/delete` | `GET/POST /webhooks`、`GET/DELETE /webhooks/:id`、`POST /webhooks/:id/rotate` | `webhooks_*` |
| `domains list/add/connect/verify/remove` | `GET/POST /domains`、`GET /domains/:host/connect`、`POST /domains/:host/verify`、`DELETE /domains/:host` | `domains_*` |

## 文件夹

文件夹是一种链接，会列出你放入其中的内容。数据模型详见[文件夹](/zh/folders)。

| 工具 | 输入 |
| --- | --- |
| `links_create` | `{ kind: "folder", name, … }` 用于创建文件夹；任何创建操作都可以传入 `folder`（slug）和 `folderDomain?`，以便在某个文件夹内创建。响应中包含 `folder` |
| `links_list` | 返回一页结果 `{ items, cursor }`（`limit` 取值 1-100，默认 50；持续回传 `cursor`，直到它为 `null`）。`q` 按词匹配；`folder: "<slug>"` 列出该文件夹下的直接内容；`folder: "root"` 列出顶层内容；`kind` 新增 `folder` 取值。每行都带有 `folder`，文件夹行还带有 `items` |
| `links_move` | `{ id, domain?, folder: string \| null, folderDomain? }` → `{ id, folder }` |
| `links_copy` | `{ id, domain? }` → `{ id, url, access, kind, folder }`（访问设置相同，分享 URL 是新的，不带共享成员） |
| `links_delete` | 对文件夹可传 `contents?: "keep" \| "delete"`（默认为 `keep`） |

`links_export` / `links_import` 新增了 `folder` 和 `access` 列，`kind` 为 `folder` 的行会创建文件夹。

## 访问与分享

新建的链接和文件夹默认是受限的：`url` 为 `https://linkdash.dev/s/<token>`，只有你和你分享给的人才能打开。可在 `links_create` 或 `links_update` 中传入 `access`：`restricted`（默认）、`link`（任何拥有分享 URL 的人）或 `public`（任何人，通过短链接访问）。如果链接要公开发布，请使用 `access: "public"`。详见[分享与访问](/zh/sharing)。

| 工具 | 输入 |
| --- | --- |
| `links_share` | `{ id, domain?, emails: string[] (1–50), role? }` → `{ id, url, access, invited, alreadyShared }` |
| `links_unshare` | `{ id, domain?, email }` → `{ id, email, removed: true }` |
| `links_shares` | `{ id, domain? }` → `{ id, access, url, people: [{ email, role, accepted, invitedAt, viaFolder? }] }`；`{ limit?, cursor? }` → 你分享出去的所有内容中的一页，格式为 `{ items, cursor }`，每项都带有 `people` |
| `links_shared` | `{ limit?, cursor? }` → 他人分享给你的内容中的一页，格式为 `{ items, cursor }`，每项都带有用于打开的 `url` |
| `links_leave` | `{ id }`（来自 `links_shared` 的 `_id` 或分享 URL）→ `{ _id, left: true }` |
| `links_update` | `access?` 用于更改谁可以打开；`resetShareLink: true` 会生成新的分享 URL（旧 URL 随即失效） |

除公开链接返回短链接外，所有响应中的 `url` 都是分享 URL。分享、取消分享、更改访问权限和重置链接各计为一次事件；退出共享不计入。

## 变体

每个链接都是一个包含一个或多个**变体**的容器。每个变体包括：内容（`url` | `file` | `text`）、各自的访问限制（`password`、`starts`、`expires`、`maxOpenings`、暂停状态）、一个 `weight`，以及可选的访客条件 `when`。如果不指定 `variants`，链接只有一个名为 `main` 的变体。链接级别的访问限制优先于变体级别的限制。每位访客只会分到一个变体：先由 `when` 匹配的变体组成候选池（若无匹配则使用无条件的变体），再按权重选取；`sticky`（默认为 `true`）让回访的访客保持在同一变体上，`restartSplit` 会重新打乱分配。包含多个变体的链接，其 `kind` 为 `group`；各变体状态不一致时，链接的 `status` 为 `mixed`。每个链接最多 20 个变体。数据结构：[HTTP API](/zh/api#变体)。

`links_create` 接受 `variants: [{ name, url | text | storageId (+ fileName, fileType, fileSize), password?, starts?, expires?, maxOpenings?, utm?, weight?, when? }]` 以替代简写形式，另外还接受 `sticky` 和 `forwardParams`。`links_update` 接受 `sticky`、`forwardParams` 和 `restartSplit`。`links_list` 可按 `kind`（新增 `group`）和 `status`（新增 `mixed`）筛选。`links_stats` 返回 `variants` 汇总数据。`links_export` / `links_import` 使用变体 CSV 格式（每个变体一行）。

| 工具 | 输入 |
| --- | --- |
| `variants_list` | `{ id, domain? }` |
| `variants_add` | `{ id, domain?, name, url \| text \| storageId (+ fileName, fileType, fileSize), password?, starts?, expires?, maxOpenings?, utm?, weight?, when? }` |
| `variants_update` | `{ id, name, domain?, newName?, url?, text?, storageId?, password?, clearPassword?, starts?, clearStarts?, expires?, clearExpires?, maxOpenings?, clearMaxOpenings?, status?, weight?, when?, clearWhen?, utm? }` |
| `variants_remove` | `{ id, name, domain? }` |

`when` 的键：`countries`、`devices`、`os`、`browsers`、`languages`、`referrerHosts`（均为字符串数组；所有已设置的键都必须匹配），以及 `params`。

**查询参数规则。**`when.params` 是一个数组，最多包含 10 条针对访客查询字符串的规则，所有规则都必须满足：`{ "params": [{ "key": "src", "op": "equals", "value": "newsletter" }] }`。`op` 可选：`equals` | `notEquals` | `includes` | `startsWith` | `endsWith` | `in`（`value` 为以 `|` 分隔的列表）| `exists` | `missing`（最后两个不需要 `value`）。键区分大小写，值按精确匹配比较。参数值永远不会存入分析数据。

**转发查询参数。**`forwardParams`（`links_create` / `links_update` 上的布尔值，默认为 `false`）会把访客的完整查询字符串追加到 URL 变体上；访客传入的值会覆盖已存储的值，包括 `utm`。仅适用于 URL 变体。该功能用于路由，不用于访问控制。

`auth create` / `auth login` / `auth logout` 不是 MCP 工具。对应关系：[api.md](https://linkdash.dev/api.md)。
