---
title: "MCP 与 ACP | Kalka docs"
description: "把 Claude Code、Cursor、Codex、Claude Desktop 等 MCP 客户端连接到 Kalka 的内置服务器，选择它们可以做什么，并安装 Kalka 智能体技能。"
url: https://kalka.design/zh/docs/mcp
language: zh-Hans
---

Kalka 与智能体之间使用两种协议：

- **MCP**，即 Model Context Protocol：在别处运行的智能体，比如终端里的 Claude Code 或 Cursor，使用 Kalka 的工具读取和编辑打开的文档。

- **ACP**，即 Agent Client Protocol：Kalka 在自己的 AI 面板中运行一个编程智能体。参见 [Kalka 中的智能体](https://kalka.design/zh/docs/agents)。

本页介绍 MCP。

## 内置服务器

桌面应用自带 MCP 服务器。它随 Kalka 启动，只在你的电脑上运行，地址是 `http://127.0.0.1:7600/mcp`。无需安装任何东西，Kalka 也不设使用上限。

**Kalka 必须处于打开状态。**服务器运行在桌面应用内部，只能看到你在 Kalka 中打开的文档。

## 一键连接智能体

打开 **设置 › MCP**。在 **连接智能体** 下，点击你的客户端旁边的 **连接**：

Claude Desktop、Claude Code、Cursor、VS Code、Windsurf、Codex、Gemini CLI、Antigravity、Kiro、Zed、LM Studio 或 opencode。

Kalka 会先在原文件旁保留一份备份，再替你写入客户端的配置。重启客户端后，Kalka 的工具会以 `kalka` 的名称出现。对于 Claude Desktop，你还可以选择 **安装扩展**。

_设置中的 MCP 标签页：“连接智能体”部分，以及可粘贴到其他 MCP 客户端的服务器配置项_

设置 › MCP。在桌面应用中，上方会列出在你电脑上找到的客户端，每个都带有“连接”。
对于其他客户端，**其他 MCP 客户端** 会显示需要粘贴到其设置中的配置项。

检查 Claude Code 能否看到 Kalka：

```
claude mcp list
```

## 智能体能做什么

智能体可以使用一百多个工具。最常用的有：

| 工具 | 作用 |
| --- | --- |
| get_selection、get_page_tree | 查看你选中了什么，以及页面的结构 |
| get_html | 以 HTML 形式读取图层 |
| write_html | 通过编写 HTML 和 CSS 添加或替换图层 |
| update_styles | 修改图层的 CSS |
| get_screenshot | 查看结果，检查工作成果 |
| get_design_guide | 读取 Kalka 的设计流程，以及需要避免的机器感习惯清单 |
| ask_user | 在 Kalka 中向你提问，附带可点击的答案 |
| get_comments、reply_to_comment | 读取评论线程并回复 |
| list_settings、update_settings | 修改 Kalka 设置，比如主题或跟随智能体 |

为 Figma 的 MCP 服务器编写的智能体，可以找到它们熟悉的同名工具：`get_metadata`、`get_variable_defs` 和 `search_design_system`。为 Figma 插件 API 编写的脚本，也能通过 `use_figma` 在打开的文档上运行。

**你的密钥只属于你。**智能体永远无法读取或修改你的 API 密钥、连接或工具访问权限。

智能体工作时，画布上会显示它的名字和正在做的事，它的修改会逐块出现。智能体的撤销只作用于它自己的步骤，绝不会撤销你的操作。

## 选择智能体可以做什么

- **设置 › 工具访问权限** 可以逐个开关工具，内置 AI 和 MCP 客户端分别设置。工具分为只读工具和会做出修改的工具。

- **设置 › MCP** 中的 **仅共享所选内容** 让客户端只能读取选中的图层，不提供任何编辑工具。

- **要求身份验证** 防止你电脑上的其他程序在没有令牌的情况下使用服务器。默认开启。

- **MCP 根目录** 限定工具可以读写文件的文件夹。

修改这些设置后，请点击 **重启 MCP 服务器** 重启服务器。

## Kalka 技能

Kalka 附带一个智能体技能：一套教智能体如何在 Kalka 中设计的说明，包含设计流程和需要避免的习惯清单。它就是 [Kalka 仓库](https://github.com/leyscore/kalka/tree/main/skills/kalka)中的 `skills/kalka` 文件夹。把它复制到你的智能体的技能文件夹中，例如 Claude Code 的 `~/.claude/skills/kalka`。

## 从 Kalka 连接其他服务器

内置 AI 也可以使用其他 MCP 服务器，这样它就能读取你的需求文档、资料或工单，而不是凭空编造内容。在 **设置 › MCP › MCP 连接** 中，通过 URL 或命令添加。

## 命令行

`kalka` 命令无需打开应用即可处理 `.fig`、`.kalka` 和 `.pen` 文件；省略文件时则作用于当前打开的文档。它可以导出、检查、lint 和运行脚本。它还没有作为软件包发布：请使用 [Bun](https://bun.sh)，在 [Kalka 仓库](https://github.com/leyscore/kalka)的克隆中运行：

```
git clone https://github.com/leyscore/kalka.git
cd kalka
bun install
bun kalka --help
```

## 连接不上时

参见[故障排除](https://kalka.design/zh/docs/troubleshooting)，尤其是端口 7600 已被占用的情况。
