Claude Code教程七| MCP 之 Pencil一、概述Pencil MCP 是什么1.1 核心定义1.2 核心价值1.3 适用人群1.4 工作原理二、环境要求与安装2.1 前置条件2.2 安装 Pencil 扩展2.3 账户激活三、MCP 配置机制详解3.1 安装后发生了什么自动配置机制3.2 自动配置到底改了什么以 Claude Code CLI 为例Claude Code CLI两个文件3.3 哪些平台支持自动配置MCP Integrations 列表3.4 其他平台的手动配置教程第 1 步找到 Pencil MCP 服务的路径第 2 步编辑 Cursor 的 mcp.json第 3 步重启 Cursor3.5 使用前的最后一步启动 Pencil四、MCP 工具全览4.1 文档操作4.2 节点读取4.3 设计操作4.4 设计辅助4.5 导出与代理五、实操流程设计到代码5.1 新建设计文件5.2 基础设计用自然语言生成5.3 精准设计结合 ASCII 草图5.4 迭代优化5.5 生成代码5.6 导出资源六、进阶技巧6.1 与 Claude 多模态模型配合效果更佳6.2 设计系统复用6.3 批量操作技巧6.4 主题变量管理6.5 Figma 文件导入6.6 与现有 AI Skills 配合七、常见问题排查7.1 MCP 工具无法调用7.2 画布未激活7.3 扩展版本更新后配置失效7.4 配置路径错误7.5 设计元素重叠或被裁剪7.6 与 Pencil 桌面端冲突结语一、概述Pencil MCP 是什么1.1 核心定义概念说明Pencil.dev基于 VS Code 扩展生态的设计画布工具被称为「程序员的 Figma」支持在 IDE 内完成像素级 UI 设计Pencil MCPPencil 提供的 Model Context Protocol模型上下文协议服务让 AI 编程工具直接调用设计、编辑、代码生成能力.pen 文件Pencil 的设计文件格式存储画布、组件、样式等设计数据只能通过 MCP 工具或 Pencil 编辑器操作1.2 核心价值优势说明零切换设计与开发在同一 IDE 内完成无需在 Figma 和代码编辑器间来回跳转AI 驱动通过自然语言描述即可生成 UI 设计AI 直接操作画布代码生成设计完成后可一键生成 Vue/React/HTML/Tailwind 等生产级代码设计系统内置组件库Lunaris、Halo、Nitro、ShadCN 等支持自定义主题变量免费使用核心功能完全免费无需订阅Figma 导入支持直接从 Figma 导入设计保留向量、文本和样式1.3 适用人群不想为 Figma AI 付费又想借助 AI 自由创作的设计师既需要写后端逻辑又想快速产出美观 UI 的全栈或后端开发者不想在 Figma 和 IDE 之间来回切换追求极致效率的前端开发者独立开发者、创业者——用一个人完成设计与开发的全流程1.4 工作原理用户自然语言描述 ↓ AI 理解意图 ↓ 调用 MCP 工具get_guidelines → get_style_guide → batch_design ↓ 操作 .pen 画布 ↓ get_screenshot 验证效果 ↓ 生成生产级代码二、环境要求与安装2.1 前置条件要求说明操作系统Windows / macOS / LinuxVS Code最新稳定版Pencil 本质是 VS Code 扩展基于 VS Code 衍生的 IDE 均可使用AI 工具Claude Code / Claude Desktop / Cursor / Trae / Windsurf 等任意支持 MCP 的工具澄清一个常见误区使用 Pencil不需要订阅官方 Claude Code 套餐也不强制使用 Claude Code。Pencil 本身就是一个 MCP 工具任何支持 MCP 协议的 AI 编程工具都能对接。2.2 安装 Pencil 扩展打开 VS Code或 Cursor、Trae 等基于 VS Code 的 IDE进入扩展市场CtrlShiftX/CmdShiftX搜索Pencil发布者High Agency点击安装搜索建议直接搜索 “Pencil” 会出很多无关结果建议搜索Pencil.dev或在发布者栏筛选High Agency。扩展信息扩展 IDhighagency.pencildev官网https://pencil.dev安装成功后VS Code 左侧会出现一个铅笔图标这就是 Pencil 的主入口。重要提示建议只安装VS Code 扩展版本不要同时安装 Pencil 独立桌面应用。两者如果同时存在可能会同时提供 MCP 服务导致冲突。2.3 账户激活点击左侧铅笔图标打开 Pencil 面板输入邮箱系统会发送 6 位验证码输入验证码完成激活三、MCP 配置机制详解这是本文最核心的部分。安装 Pencil 扩展后最关键的一步就是配置 MCP 服务——让你的 AI 编程工具能够调用 Pencil 的设计能力。3.1 安装后发生了什么自动配置机制安装 Pencil 扩展并激活账户后打开扩展的设置页面插件商店 → Pencil 右侧齿轮 → 扩展设置你会看到一个MCP Integrations面板关键点默认全部开启。这意味着安装扩展后Pencil 会自动帮你配置 MCP— 不需要你手动改任何文件每个开关对应一个 AI 工具— 开启 自动写入配置关闭 自动删除配置每次启动 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 在哪里第二个解决能不能用 Pencil3.3 哪些平台支持自动配置MCP Integrations 列表设置页面“MCP Integrations in Terminal”区域列出的7 个平台都可以通过开关一键自动配置平台说明配置文件配置键名需单独权限文件Claude Code CLIClaude 命令行工具最常用~/.claude.jsonmcpServers是~/.claude/settings.jsonGemini CLIGoogle Gemini 命令行工具~/.gemini/settings.jsonmcpServers否Claude DesktopClaude 桌面客户端claude_desktop_config.jsonmcpServers否Codex CLIOpenAI Codex 命令行工具~/.codex/config.tomlmcp_serversTOML 格式否OpenCode CLI开源 AI 编程 CLI~/.config/opencode/opencode.jsonmcp否Kiro CLIKiro 命令行工具~/.kiro/settings/mcp.jsonmcpServers否Copilot IDEVS Code 内置的 GitHub Copilot项目根目录mcp.jsonservers否为什么 Claude Code CLI 需要单独配权限Claude Code 有独立的权限管理系统允许精细控制每个 MCP 工具的调用权限。其他平台配置了 MCP 服务就能直接使用。使用步骤在 Pencil 设置页面确认对应平台的开关已开启默认全部开启重启对应的 AI 工具打开一个.pen文件即可开始使用3.4 其他平台的手动配置教程以下平台不在 MCP Integrations 列表中需要手动配置平台配置文件/入口Cursor~/.cursor/mcp.json或 Settings → Tools MCPWindsurf~/.codeium/windsurf/mcp_config.jsonTrae CNAI 面板 → 设置 → MCP → 添加 → 手动配置其他 VS Code 系列 IDE对应 IDE 的 MCP 配置入口提示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在 VS Code或你使用的 IDE中点击左侧铅笔图标看到 Pencil 面板出现说明已启动确保.pen文件处于活跃标签页状态只有 Pencil 启动且画布激活时AI 才能调用 MCP 工具操作设计。四、MCP 工具全览Pencil MCP 提供16 个工具按功能分类如下4.1 文档操作工具功能open_document打开现有 .pen 文件或创建新文档get_editor_state获取当前活跃编辑器、用户选择等状态信息4.2 节点读取工具功能batch_get批量搜索/读取节点支持模式匹配和 ID 查询get_screenshot获取指定节点的截图与 Claude 多模态模型完美适配无需其他工具中转get_variables获取文档中的变量和主题定义snapshot_layout检查布局结构发现裁剪、重叠等问题4.3 设计操作工具功能batch_design批量执行插入/复制/更新/替换/移动/删除操作每次建议不超过 25 个操作set_variables更新变量和主题定义replace_all_matching_properties全局替换匹配的属性值find_empty_space_on_canvas在画布上寻找空白区域4.4 设计辅助工具功能get_guidelines获取设计指南支持 8 个主题web-app/mobile-app/slides/design-system/code/table/tailwind/landing-pageget_style_guide根据标签获取风格指南温馨、科技、简约等风格标签get_style_guide_tags获取所有可用的风格标签列表search_all_unique_properties搜索文档中的唯一属性值4.5 导出与代理工具功能export_nodes导出节点为 PNG / JPEG / WEBP / PDFspawn_agents启动子代理任务实验性功能五、实操流程设计到代码5.1 新建设计文件方式一通过 VS Code 界面点击 Pencil 面板左上角的New .pen file新建并打开一个空白画布方式二通过 MCP 工具调用 mcp__pencil__open_document参数 filePathOrTemplate: new5.2 基础设计用自然语言生成先用一个简单的提示词试试水使用 Pencil MCP在当前活跃的画布上设计一个运维相关的 App 登录页 要求有指纹登录、账号登录、一键登录、手机验证登录。 类似飞书的 B 端简洁风格iOS 风格。AI 会自动执行以下流程调用get_guidelines获取设计指南调用get_style_guide获取匹配的风格调用batch_design创建画布、组件、布局调用set_variables设置主题颜色调用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圆角改为 8px5.5 生成代码推荐方式使用子代理节省 TokenMCP 工具在处理复杂任务时会消耗大量上下文 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.lib.penLunaris 设计系统组件halo.lib.penHalo 设计系统组件nitro.lib.penNitro 设计系统组件shadcn.lib.pen基于 ShadCN/ui 的组件库使用方式参考 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” 或权限被拒绝排查步骤检查~/.claude/settings.json是否包含mcp__pencil权限检查~/.claude.json中mcpServers.pencil配置是否存在确认command路径中的 exe 文件实际存在版本更新后路径可能变化完全重启 AI 工具关闭终端窗口再重新打开确保后台进程也退出7.2 画布未激活症状AI 提示 “No active editor” 或 “Please open a .pen file first”解决方案在 IDE 中打开一个.pen文件确保.pen文件标签页处于当前活跃状态点击左侧铅笔图标确保 Pencil 已启动重新发送指令7.3 扩展版本更新后配置失效症状更新 Pencil 扩展后MCP 工具突然无法调用原因扩展安装目录名包含版本号如highagency.pencildev-0.6.36更新后版本号变化导致command路径失效。解决方案打开 Pencil 扩展设置页面扩展会自动重新检测并写入新路径如果自动修复未生效手动更新配置文件中的路径重启 AI 工具7.4 配置路径错误症状MCP 服务启动失败常见错误路径包含中文或空格使用了相对路径而非绝对路径正确格式示例WindowsC:\\Users\\YourName\\.vscode\\extensions\\highagency.pencildev-0.6.36\\out\\mcp-server-windows-x64.exe7.5 设计元素重叠或被裁剪症状组件显示不完整或相互覆盖解决方案调用 snapshot_layout 检查布局问题 根据返回的 problems 列表逐项修复7.6 与 Pencil 桌面端冲突症状MCP 服务反复启动失败或连接不稳定解决方案卸载 Pencil 独立桌面应用只保留 VS Code 扩展版本。结语Pencil MCP 将 UI 设计能力直接嵌入 AI 编程工作流实现了「设计即代码」的愿景安装即配置— 扩展安装后默认开启所有支持的平台自动写入 MCP 配置零门槛7 个平台开箱即用— Claude Code / Claude Desktop / Codex / Gemini / OpenCode / Kiro / Copilot IDE重启即可使用其他平台也不难— Cursor / Windsurf / Antigravity / Trae CN 等点击 Copy MCP config 按钮改一个参数即可接入高效设计— 用自然语言或 ASCII 草图驱动 AI 完成像素级 UI 设计无缝交付— 通过子代理生成生产级代码节省 Token 的同时保持还原度在 AI 时代你对工具链的选择将直接决定你的生产力天花板。参考文章【1】Pencil.dev评测基于IDE与MCP的设计工具如何解决设计到开发断层问题【2】手把手教你在Trae CN里如何配置Pencil MCP Server