Claude Code 配置指南：三层配置体系与 Figma MCP 连接

前言

在使用 Claude Code CLI 进行开发时，我们经常需要将设计稿转换为代码。通过 MCP (Model Context Protocol) 连接 Figma，可以让 Claude 直接读取设计文件并生成对应的代码。本文将详细介绍 Claude Code 的配置文件体系，以及如何配置 Figma MCP 连接。

一、三个配置文件的层级关系

Claude Code 使用三层配置文件系统，它们各司其职又相互配合：

全局配置 (所有项目)
    ↓
项目配置 (当前项目)
    ↓
本地权限配置 (团队共享)

1.1 全局用户配置：`~/.claude.json`

位置：用户主目录（/Users/你的用户名/.claude.json）
作用范围：影响所有项目

这是 Claude Code 的核心配置文件，存储了：

{
  "theme": "light",                    // 主题设置
  "autoUpdates": true,                 // 自动更新
  "numStartups": 83,                   // 启动次数统计
  "projects": {                        // 每个项目的配置
    "/path/to/project": {
      "mcpServers": { ... },          // MCP 服务器配置
      "hasTrustDialogAccepted": true, // 项目信任状态
      "lastSessionId": "...",         // 会话历史
      "exampleFiles": [ ... ]         // 示例文件
    }
  }
}

关键特性：

记录所有项目的使用历史和统计信息
存储每个项目的 MCP 服务器配置
作为配置缓存，提高启动速度
不应该手动编辑，由 Claude Code 自动管理

1.2 项目级 MCP 配置：`.mcp.json`

位置：项目根目录
作用范围：仅当前项目

这个文件定义了项目可以使用的 MCP 服务器：

{
  "mcpServers": {
    "figma": {
      "type": "http",
      "url": "http://127.0.0.1:3845/mcp"
    }
  }
}

关键特性：

声明项目可用的外部服务连接
支持多种 MCP 服务器（Figma、GitHub、数据库等）
建议加入 .gitignore，因为连接信息可能因人而异
首次使用时会自动同步到 ~/.claude.json

1.3 项目级权限配置：`.claude/settings.local.json`

位置：项目根目录的 .claude/ 文件夹
作用范围：仅当前项目

这个文件控制 Claude 的行为权限：

{
  "permissions": {
    "allow": [
      "Bash(yarn tsc:*)",                      // 允许 TypeScript 编译
      "Bash(yarn lint:*)",                     // 允许代码检查
      "mcp__figma__get_design_context",        // 允许读取 Figma 设计
      "mcp__figma__get_screenshot",            // 允许获取设计截图
      "mcp__figma__get_metadata",              // 允许读取元数据
      "mcp__figma__get_variable_defs"          // 允许读取设计变量
    ]
  },
  "enabledMcpjsonServers": [
    "figma"                                     // 启用 Figma MCP 服务器
  ]
}

关键特性：

预批准常用命令，减少交互提示
控制哪些 MCP 服务器被实际启用
建议提交到 Git，让团队成员共享配置
提高工作效率，无需每次批准相同操作

二、三个文件如何协同工作

让我们通过一个实际场景来理解它们的关系：

场景：Claude 读取 Figma 设计

用户：读取 Figma 设计 https://figma.com/design/xxx?node-id=444:4461
Claude 检查 .claude/settings.local.json
- 确认 "figma" 在 enabledMcpjsonServers 中
- 确认 mcp__figma__get_design_context 在 allow 列表中
Claude 查找 .mcp.json
- 获取 Figma MCP 服务器连接信息
- URL: http://127.0.0.1:3845/mcp
Claude 连接到本地 Figma MCP 服务器
- 调用 get_design_context API
- 获取设计代码和截图
结果自动同步到 ~/.claude.json
- 记录使用历史
- 缓存 MCP 服务器配置

配置优先级：

.claude/settings.local.json (项目权限)
        ↓ 控制是否启用
.mcp.json (连接信息)
        ↓ 自动同步到
~/.claude.json (全局缓存)

三、配置 Figma MCP 连接：完整指南

3.1 前置要求

安装 Claude Code CLI

npm install -g @anthropic-ai/claude-code

安装 Figma 桌面客户端
- 从 https://www.figma.com/downloads/ 下载
- 必须使用桌面版，浏览器版不支持 MCP
启用 Figma MCP 服务器
- 打开 Figma 桌面应用
- 进入 Preferences → Integrations
- 启用 "MCP Server"（默认端口 3845）

3.2 配置步骤

步骤 1：创建 .mcp.json 文件

在项目根目录创建 .mcp.json：

{
  "mcpServers": {
    "figma": {
      "type": "http",
      "url": "http://127.0.0.1:3845/mcp"
    }
  }
}

说明：

figma：MCP 服务器的名称（可自定义）
type：连接类型（http 或 stdio）
url：Figma 本地服务器地址（默认 3845 端口）

步骤 2：创建权限配置文件

创建 .claude/settings.local.json：

{
  "permissions": {
    "allow": [
      "mcp__figma__get_design_context",
      "mcp__figma__get_screenshot",
      "mcp__figma__get_metadata",
      "mcp__figma__get_variable_defs",
      "mcp__figma__create_design_system_rules",
      "mcp__figma__get_figjam"
    ]
  },
  "enabledMcpjsonServers": [
    "figma"
  ]
}

Figma MCP 工具说明：

工具名称	功能	必需
`get_design_context`	获取设计代码和上下文	✅
`get_screenshot`	获取设计节点截图	✅
`get_metadata`	获取节点元数据（XML格式）	推荐
`get_variable_defs`	获取设计变量定义	推荐
`create_design_system_rules`	生成设计系统规则	可选
`get_figjam`	读取 FigJam 白板	可选

步骤 3：配置 .gitignore

建议将 .mcp.json 加入 .gitignore：

# Claude Code
.mcp.json

而 .claude/settings.local.json 应该提交到 Git，方便团队共享。

3.3 验证配置

启动 Claude Code 并测试连接：

cd your-project
claude

在 Claude 中输入：

读取这个 Figma 设计：https://www.figma.com/design/xxx?node-id=123:456

如果配置正确，Claude 会：

自动连接到本地 Figma 客户端
读取设计节点信息
返回设计代码和截图

四、常见问题排查

4.1 连接失败：ECONNREFUSED

原因：Figma 桌面客户端未启动或 MCP 服务器未启用

解决：

确保 Figma 桌面应用正在运行
检查 Figma → Preferences → Integrations → MCP Server 已启用
验证端口 3845 未被占用：
```
lsof -i :3845
```

4.2 权限被拒绝

原因：.claude/settings.local.json 中未启用相应工具

解决：
在 permissions.allow 数组中添加对应的 MCP 工具名称

4.3 无法读取设计

原因：Figma 文件未在桌面客户端中打开

解决：
在 Figma 桌面应用中打开目标设计文件，然后再让 Claude 读取

五、最佳实践

5.1 团队协作配置

推荐的文件管理策略：

.gitignore:
  - .mcp.json          # 个人连接配置，不提交

Git 仓库:
  + .claude/
    + settings.local.json   # 团队共享权限配置

原因：

.mcp.json 可能包含个人本地路径或端口配置
.claude/settings.local.json 是团队通用的权限配置

5.2 权限配置建议

开发命令权限：

{
  "permissions": {
    "allow": [
      "Bash(yarn *)",
      "Bash(npm *)",
      "Bash(git status)",
      "Bash(git diff:*)",
      "Bash(yarn lint:*)",
      "Bash(yarn test:*)"
    ]
  }
}

安全提示：

不要盲目允许所有命令（Bash(*)）
避免允许危险命令（rm -rf、sudo 等）
定期审查权限列表

5.3 多项目配置

如果你有多个项目都需要 Figma 连接：

方法 1：每个项目单独配置

project-a/
  └── .mcp.json
  └── .claude/settings.local.json

project-b/
  └── .mcp.json
  └── .claude/settings.local.json

方法 2：使用符号链接共享配置

ln -s ~/config/.mcp.json project-a/.mcp.json
ln -s ~/config/.mcp.json project-b/.mcp.json

六、进阶用法

6.1 配置多个 MCP 服务器

.mcp.json 支持配置多个服务器：

{
  "mcpServers": {
    "figma": {
      "type": "http",
      "url": "http://127.0.0.1:3845/mcp"
    },
    "github": {
      "type": "http",
      "url": "http://127.0.0.1:3000/mcp"
    },
    "postgres": {
      "type": "stdio",
      "command": "mcp-postgres",
      "args": ["--connection-string", "postgresql://localhost/db"]
    }
  }
}

6.2 自定义 Figma 端口

如果 3845 端口被占用，可以在 Figma 中修改端口：

Figma → Preferences → Integrations
修改 MCP Server Port（例如 3846）
更新 .mcp.json：

{
  "mcpServers": {
    "figma": {
      "type": "http",
      "url": "http://127.0.0.1:3846/mcp"
    }
  }
}

6.3 读取设计变量

配置完成后，可以让 Claude 读取 Figma 设计变量：

读取这个设计的颜色变量：https://www.figma.com/design/xxx

Claude 会调用 get_variable_defs 返回：

{
  "icon/default/primary": "#08050d",
  "icon/default/secondary": "#949494",
  "spacing/xs": "4px",
  "spacing/sm": "8px"
}

七、总结

通过理解 Claude Code 的三层配置文件系统，我们可以：

全局配置 (~/.claude.json)：自动管理，无需关心
MCP 配置 (.mcp.json)：定义外部服务连接
权限配置 (.claude/settings.local.json)：控制功能启用

配置 Figma MCP 连接后，Claude 可以：

直接读取 Figma 设计文件
生成对应的前端代码
获取设计变量和样式
将设计稿转换为 React/React Native 组件

这大大提升了设计到代码的转换效率，让 AI 辅助开发更加智能和高效。

王亚飞的博客

逃离安逸区

Claude Code 配置指南：通过 MCP 连接 Figma 本地客户端

Claude Code 配置指南：三层配置体系与 Figma MCP 连接

前言

一、三个配置文件的层级关系

1.1 全局用户配置：`~/.claude.json`

1.2 项目级 MCP 配置：`.mcp.json`

1.3 项目级权限配置：`.claude/settings.local.json`

二、三个文件如何协同工作

三、配置 Figma MCP 连接：完整指南

3.1 前置要求

3.2 配置步骤

3.3 验证配置

四、常见问题排查

4.1 连接失败：ECONNREFUSED

4.2 权限被拒绝

4.3 无法读取设计

五、最佳实践

5.1 团队协作配置

5.2 权限配置建议

5.3 多项目配置

六、进阶用法

6.1 配置多个 MCP 服务器

6.2 自定义 Figma 端口

6.3 读取设计变量

七、总结

参考资源

您还没有登录，请您登录后发表评论。

Claude Code 配置指南：三层配置体系与 Figma MCP 连接

前言

一、三个配置文件的层级关系

1.1 全局用户配置：~/.claude.json

1.2 项目级 MCP 配置：.mcp.json

1.3 项目级权限配置：.claude/settings.local.json

二、三个文件如何协同工作

三、配置 Figma MCP 连接：完整指南

3.1 前置要求

3.2 配置步骤

3.3 验证配置

四、常见问题排查

4.1 连接失败：ECONNREFUSED

4.2 权限被拒绝

4.3 无法读取设计

五、最佳实践

5.1 团队协作配置

5.2 权限配置建议

5.3 多项目配置

六、进阶用法

6.1 配置多个 MCP 服务器

6.2 自定义 Figma 端口

6.3 读取设计变量

七、总结

参考资源

您还没有登录，请您登录后发表评论。

1.1 全局用户配置：`~/.claude.json`

1.2 项目级 MCP 配置：`.mcp.json`

1.3 项目级权限配置：`.claude/settings.local.json`