> For the complete documentation index, see [llms.txt](https://getsquish.gitbook.io/squish/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://getsquish.gitbook.io/squish/zh/ru-men/quickstart-mcp.md).

# 快速开始：MCP

**让 AI 能随机访问视频。** Squish MCP 服务器是一个轻量的 stdio 服务器，基于与 CLI 相同的引擎，只暴露一个工具—— **`squish_video`** ——它会把本地视频转换成带时间戳的 contact sheets（缩略图联系表），然后由 agent 用视觉能力读取。引擎相同，输出也与 CLI 相同：一切都在 agent 所运行的机器上执行；绝不会上传任何内容，而且每一份密度都是免费的。

## 需求

Node ≥ 20 和 `ffmpeg` + `ffprobe` 在 PATH 中（macOS `brew install ffmpeg` · Ubuntu `sudo apt-get install ffmpeg`）。服务器本身直接通过 npm 运行，使用 `npx` ——无需安装步骤。

## 注册服务器

只需一个配置块，就能把服务器注册到任何 stdio MCP 客户端：

```json
{
  "mcpServers": {
    "squish": { "command": "npx", "args": ["-y", "@getsquish/squish", "mcp"] }
  }
}
```

{% tabs %}
{% tab title="Claude Code" %}
一条命令：

```bash
claude mcp add squish -- npx -y @getsquish/squish mcp
```

或者把上面的配置块提交为 `.mcp.json` 放在项目根目录，这样仓库里协作的所有人都能共享这个服务器。
{% endtab %}

{% tab title="Claude Desktop" %}
Settings → Developer → **Edit Config** 会打开 `claude_desktop_config.json`。添加上面的配置块，保存，然后重启 Claude Desktop。
{% endtab %}

{% tab title="Cursor" %}
把上面的配置块添加到 `.cursor/mcp.json` 里（或者放到 `~/.cursor/mcp.json` 用于所有项目）——agent 会自己处理本地片段。
{% endtab %}
{% endtabs %}

任何其他 stdio MCP 客户端的用法都一样——配置块完全相同。

## 验证是否可用

让 agent 回答：

> 在 /path/to/clip.mov 中发生了什么？使用 squish\_video。

agent 应该调用 `squish_video`，返回 sheet 文件路径以及每一帧的时间码，使用视觉能力读取 sheet，并在回答中引用每个单元格里标注的时间码。

## 该工具

一个工具， **`squish_video`** — `{ video_path, density?, start?, end?, out_dir? }` → CLI 协议 **以及** `timecodes[][]` （每张 sheet 每帧一个； `m:ss`，亚秒级 `m:ss.d` 当窗口较短时），标注 `"contract": "squish-mcp-v0"`:

```json
{
  "input": "/abs/path/clip.mov",
  "duration": 20.275,
  "frames": 9,
  "sheets": 1,
  "files": ["/abs/path/out/clip.sheet-1.jpg"],
  "warnings": [],
  "timecodes": [["0:01","0:03","0:05","0:07","0:10","0:12","0:14","0:16","0:19"]],
  "contract": "squish-mcp-v0"
}
```

错误会作为 MCP 工具错误抛出，而不是让程序崩溃。 `契约` 字段是版本标记——解析它可以检测破坏性变更。

## 继续导航

`start` / `end` 接受秒数或 sheet 时间码，并将运行范围限制到某个区间——时间码始终相对于源视频保持绝对值，因此 agent 可以反复深入：概览 → 在 sheet 上定位一个范围 → 再次调用 `squish_video` ，并将 `start`/`end` 设置为它看到的时间码 → 更窄窗口下更密集的 sheets。见 [导航循环](/squish/zh/primitive/the-navigation-loop.md).

## 下一步

* [导航循环](/squish/zh/primitive/the-navigation-loop.md) ——概览 → 放大 → 引用。
* [MCP 参考](/squish/zh/can-kao/mcp.md) ——完整的工具 schema 和结果协议。
* [CLI 快速入门](/squish/zh/ru-men/quickstart-cli.md) ——同一个引擎也可从 shell 中使用，适用于脚本和支持 shell 的 agent。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://getsquish.gitbook.io/squish/zh/ru-men/quickstart-mcp.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.