Claude Code教程（七）| MCP 之 Pencil

一、概述：Pencil MCP 是什么

1.1 核心定义

1.2 核心价值

1.3 适用人群

• 不想为 Figma AI 付费，又想借助 AI 自由创作的设计师
• 既需要写后端逻辑，又想快速产出美观 UI 的全栈或后端开发者
• 不想在 Figma 和 IDE 之间来回切换，追求极致效率的前端开发者
• 独立开发者、创业者——用一个人完成设计与开发的全流程

1.4 工作原理

用户自然语言描述 ↓ AI 理解意图 ↓ 调用 MCP 工具（get_guidelines → get_style_guide → batch_design） ↓ 操作 .pen 画布 ↓ get_screenshot 验证效果 ↓ 生成生产级代码

二、环境要求与安装

2.1 前置条件

澄清一个常见误区：使用 Pencil不需要订阅官方 Claude Code 套餐，也不强制使用 Claude Code。Pencil 本身就是一个 MCP 工具，任何支持 MCP 协议的 AI 编程工具都能对接。

2.2 安装 Pencil 扩展

1. 打开 VS Code（或 Cursor、Trae 等基于 VS Code 的 IDE）
2. 进入扩展市场（Ctrl+Shift+X/Cmd+Shift+X）
3. 搜索Pencil（发布者：High Agency）
4. 点击安装

搜索建议：直接搜索 “Pencil” 会出很多无关结果，建议搜索Pencil.dev或在发布者栏筛选High Agency。

扩展信息：

• 扩展 ID：highagency.pencildev
• 官网：https://pencil.dev

安装成功后，VS Code 左侧会出现一个铅笔图标，这就是 Pencil 的主入口。

重要提示：建议只安装VS Code 扩展版本，不要同时安装 Pencil 独立桌面应用。两者如果同时存在，可能会同时提供 MCP 服务，导致冲突。

2.3 账户激活

1. 点击左侧铅笔图标打开 Pencil 面板
2. 输入邮箱，系统会发送 6 位验证码
3. 输入验证码完成激活

三、MCP 配置机制详解

这是本文最核心的部分。安装 Pencil 扩展后，最关键的一步就是配置 MCP 服务——让你的 AI 编程工具能够调用 Pencil 的设计能力。

3.1 安装后发生了什么？自动配置机制

安装 Pencil 扩展并激活账户后，打开扩展的设置页面（插件商店 → Pencil 右侧齿轮 → 扩展设置），你会看到一个MCP Integrations面板：

关键点：默认全部开启。这意味着：

1. 安装扩展后，Pencil 会自动帮你配置 MCP— 不需要你手动改任何文件
2. 每个开关对应一个 AI 工具— 开启 = 自动写入配置，关闭 = 自动删除配置
3. 每次启动 Pencil 时同步— 确保配置与开关状态一致

3.2 自动配置到底改了什么？以 Claude Code CLI 为例

Claude Code CLI 是最常用的 AI 编程工具，我们以它为例，看看开启开关后 Pencil 自动修改了哪些文件。

前提条件：你本地需要先安装对应的 AI 工具。Pencil 只会为已安装的工具写入配置，没安装的会跳过。

Claude Code CLI：两个文件

Claude Code CLI 比较特殊，它的 MCP 配置和权限配置分在两个文件中：

文件一：~/.claude.json— MCP 服务配置（告诉 Claude Code Pencil 在哪里）

{"mcpServers":{"pencil":{"command":"C:\\Users\\你的用户名\\.vscode\\extensions\\highagency.pencildev-0.6.36\\out\\mcp-server-windows-x64.exe","args":["--app","visual_studio_code"],"env":{},"type":"stdio"}}}

文件二：~/.claude/settings.json— 权限配置（告诉 Claude Code 允许调用 Pencil 工具）

{"permissions":{"allow":["mcp__pencil"]}}

这两个文件缺一不可：

• 第一个解决"Pencil 在哪里"
• 第二个解决"能不能用 Pencil"

3.3 哪些平台支持自动配置？（MCP Integrations 列表）

设置页面“MCP Integrations in Terminal”区域列出的7 个平台，都可以通过开关一键自动配置：

为什么 Claude Code CLI 需要单独配权限？Claude Code 有独立的权限管理系统，允许精细控制每个 MCP 工具的调用权限。其他平台配置了 MCP 服务就能直接使用。

使用步骤：

1. 在 Pencil 设置页面确认对应平台的开关已开启（默认全部开启）
2. 重启对应的 AI 工具
3. 打开一个.pen文件，即可开始使用

3.4 其他平台的手动配置教程

以下平台不在 MCP Integrations 列表中，需要手动配置：

提示：Cursor 和 Windsurf 支持全局配置（~/.cursor/mcp.json）和项目级配置（.cursor/mcp.json），建议使用全局配置一次搞定所有项目。

下面以Cursor为例演示手动配置步骤：

第 1 步：找到 Pencil MCP 服务的路径

Pencil MCP 服务的 exe 文件位于你的 VS Code 扩展目录：

C:\Users\你的用户名\.vscode\extensions\highagency.pencildev-版本号\out\mcp-server-windows-x64.exe

快速获取路径：在 Pencil 设置页面底部点击Copy MCP config，复制出来的command字段就是完整路径。

第 2 步：编辑 Cursor 的 mcp.json

打开或创建~/.cursor/mcp.json（全局配置），写入以下内容：

{"mcpServers":{"pencil":{"command":"C:\\Users\\你的用户名\\.vscode\\extensions\\highagency.pencildev-0.6.36\\out\\mcp-server-windows-x64.exe","args":["--app","cursor"],"env":{}}}}

注意格式差异：Pencil 的 “Copy MCP config” 输出的格式不能直接粘贴到 Cursor 的 mcp.json 中。Cursor 需要用mcpServers键包裹，且不需要name和transport字段。

第 3 步：重启 Cursor

保存配置文件后，重启 Cursor 即可生效。

3.5 使用前的最后一步：启动 Pencil

无论自动还是手动配置，每次使用前都需要先启动 Pencil：

1. 在 VS Code（或你使用的 IDE）中点击左侧铅笔图标
2. 看到 Pencil 面板出现，说明已启动
3. 确保.pen文件处于活跃标签页状态

只有 Pencil 启动且画布激活时，AI 才能调用 MCP 工具操作设计。

四、MCP 工具全览

Pencil MCP 提供16 个工具，按功能分类如下：

4.1 文档操作

4.2 节点读取

4.3 设计操作

4.4 设计辅助

4.5 导出与代理

五、实操流程：设计到代码

5.1 新建设计文件

方式一：通过 VS Code 界面

1. 点击 Pencil 面板左上角的New .pen file
2. 新建并打开一个空白画布

方式二：通过 MCP 工具

调用 mcp__pencil__open_document，参数 filePathOrTemplate: "new"

5.2 基础设计：用自然语言生成

先用一个简单的提示词试试水：

使用 Pencil MCP，在当前活跃的画布上，设计一个运维相关的 App 登录页， 要求有指纹登录、账号登录、一键登录、手机验证登录。 类似飞书的 B 端简洁风格，iOS 风格。

AI 会自动执行以下流程：

1. 调用get_guidelines获取设计指南
2. 调用get_style_guide获取匹配的风格
3. 调用batch_design创建画布、组件、布局
4. 调用set_variables设置主题颜色
5. 调用get_screenshot截图验证效果

提示：第一次生成的效果可能不够理想，这通常是因为提示词过于简单。可以通过迭代优化来提升质量。

5.3 精准设计：结合 ASCII 草图

对于布局要求精确的场景，可以用 ASCII 草图约束 AI 的输出：

使用 Pencil MCP 工具，在当前活跃的画布上，按照以下布局重新设计： ┌─────────────────────────┐ │ Status Bar │ ├─────────────────────────┤ │ │ │ ┌───────────────┐ │ │ │ App Logo │ │ │ └───────────────┘ │ │ │ │ ┌───────────────┐ │ │ │ Email Input │ │ │ └───────────────┘ │ │ ┌───────────────┐ │ │ │Password Input │ │ │ └───────────────┘ │ │ │ │ ┌───────────────┐ │ │ │ Login Button │ │ │ └───────────────┘ │ │ │ │ ─── or continue with ──│ │ │ │ [Fingerprint] [Phone] │ │ │ └─────────────────────────┘

结合 ASCII 草图后，AI 的输出还原度会显著提高。如果位置有偏移，可以手动拖拽或再次指示 AI 调整。

5.4 迭代优化

检查布局问题：

调用 snapshot_layout 检查当前画布，看看有没有元素被裁剪或重叠

获取截图验证：

给我看一下当前设计的效果

修改特定元素：

把登录按钮的颜色改成蓝色 #4A90D9，圆角改为 8px

5.5 生成代码

推荐方式：使用子代理（节省 Token）

MCP 工具在处理复杂任务时会消耗大量上下文 Token。为了避免占满主对话的上下文窗口，建议开启子代理执行代码生成：

设计效果满意了。新开一个子代理，根据当前画布设计生成 Vue 3 + Tailwind CSS 代码， 代码输出到 src/views/login/ 目录。

子代理拥有独立的上下文窗口，能有效控制 Token 消耗，不影响主对话的对话历史。

5.6 导出资源

导出画布中的主框架为 PNG 图片，保存到 ./assets/ 目录

AI 调用export_nodes完成 2x 高清导出（默认 4096px 最大分辨率）。

六、进阶技巧

6.1 与 Claude 多模态模型配合效果更佳

Pencil 的get_screenshot工具与 Claude 多模态模型（如 Claude Opus/Sonnet 4.5+）是完美适配的——截图直接传给模型分析，无需通过其他 MCP 工具中转，避免了信息丢失。

如果你使用的是 Claude 模型，设计验证的精度会比其他模型更高。

6.2 设计系统复用

Pencil 内置以下设计系统，位于扩展安装目录的out/data/文件夹：

使用方式：

参考 Lunaris 设计系统的风格，创建一个卡片组件

也支持集成自定义设计系统，例如 Ant Design：

帮我集成 Ant Design 的设计规范到 Pencil 中

AI 会自动到网上搜索规范并集成到 Pencil 中。

6.3 批量操作技巧

batch_design支持单次调用执行多个操作：

// 示例：批量创建多个按钮I(parent,{type:"frame",name:"btn-primary",...})I(parent,{type:"frame",name:"btn-secondary",...})I(parent,{type:"frame",name:"btn-danger",...})

注意：每次调用建议不超过 25 个操作，大型设计应分批处理。

6.4 主题变量管理

定义变量：

{"primary":"#FF6B6B","secondary":"#4ECDC4","background":"#FFFFFF","text":"#2D3436"}

使用变量：
在节点属性中使用$前缀引用：fill: "$primary"

修改主题时只需更新变量值，所有引用该变量的元素会自动更新。

6.5 Figma 文件导入

Pencil 支持直接从 Figma 导入设计文件，保留向量、文本和样式信息。在 Pencil 工具栏中选择 “Import Figma” 即可。

当前限制：Pencil 支持导入 Figma 文件，但暂不支持导出为 Figma 格式。

6.6 与现有 AI Skills 配合

如果你已经在使用ascii-ui-designer、frontend-design、ui-ux-pro-max等 AI Skills，引入 Pencil 后可以形成互补：

• Skills 提供设计思路和规范
• Pencil 提供精确的画布操作和代码生成

七、常见问题排查

7.1 MCP 工具无法调用

症状：AI 提示 “tool not found” 或权限被拒绝

排查步骤：

1. 检查~/.claude/settings.json是否包含"mcp__pencil"权限
2. 检查~/.claude.json中mcpServers.pencil配置是否存在
3. 确认command路径中的 exe 文件实际存在（版本更新后路径可能变化）
4. 完全重启 AI 工具（关闭终端窗口再重新打开，确保后台进程也退出）

7.2 画布未激活

症状：AI 提示 “No active editor” 或 “Please open a .pen file first”

解决方案：

1. 在 IDE 中打开一个.pen文件
2. 确保.pen文件标签页处于当前活跃状态
3. 点击左侧铅笔图标确保 Pencil 已启动
4. 重新发送指令

7.3 扩展版本更新后配置失效

症状：更新 Pencil 扩展后，MCP 工具突然无法调用

原因：扩展安装目录名包含版本号（如highagency.pencildev-0.6.36），更新后版本号变化，导致command路径失效。

解决方案：

1. 打开 Pencil 扩展设置页面，扩展会自动重新检测并写入新路径
2. 如果自动修复未生效，手动更新配置文件中的路径
3. 重启 AI 工具

7.4 配置路径错误

症状：MCP 服务启动失败

常见错误：

• 路径包含中文或空格
• 使用了相对路径而非绝对路径

正确格式示例（Windows）：

C:\\Users\\YourName\\.vscode\\extensions\\highagency.pencildev-0.6.36\\out\\mcp-server-windows-x64.exe

7.5 设计元素重叠或被裁剪

症状：组件显示不完整或相互覆盖

解决方案：

调用 snapshot_layout 检查布局问题 根据返回的 problems 列表逐项修复

7.6 与 Pencil 桌面端冲突

症状：MCP 服务反复启动失败或连接不稳定

解决方案：卸载 Pencil 独立桌面应用，只保留 VS Code 扩展版本。

结语

Pencil MCP 将 UI 设计能力直接嵌入 AI 编程工作流，实现了「设计即代码」的愿景：

1. 安装即配置— 扩展安装后默认开启所有支持的平台，自动写入 MCP 配置，零门槛
2. 7 个平台开箱即用— Claude Code / Claude Desktop / Codex / Gemini / OpenCode / Kiro / Copilot IDE，重启即可使用
3. 其他平台也不难— Cursor / Windsurf / Antigravity / Trae CN 等，点击 Copy MCP config 按钮，改一个参数即可接入
4. 高效设计— 用自然语言或 ASCII 草图驱动 AI 完成像素级 UI 设计
5. 无缝交付— 通过子代理生成生产级代码，节省 Token 的同时保持还原度

在 AI 时代，你对工具链的选择，将直接决定你的生产力天花板。

参考文章：
【1】Pencil.dev评测：基于IDE与MCP的设计工具如何解决设计到开发断层问题
【2】手把手教你在Trae CN里，如何配置Pencil MCP Server