Feishu Connect

飞书 MCP 连接管理

管理飞书 MCP 的连接、授权和 Token 刷新。

两个飞书 MCP

功能列表

检测 MCP 状态

步骤 1: 读取 MCP 配置

读取项目根目录的 .mcp.json:

{
  "mcpServers": {
    "feishu": { ... },
    "feishu-official": { ... }
  }
}

步骤 2: 读取 Token 配置

检查官方 MCP 的 UAT Token 状态：

1. 检查环境变量 FEISHU_UAT 是否存在
2. 检查本地缓存的 Token（.claude/feishu/uat.json）

步骤 3: 输出状态

📋 飞书 MCP 状态检测

┌─────────────────┬──────────┬────────────────────────────────┐
│ MCP             │ 状态     │ 详情                           │
├─────────────────┼──────────┼────────────────────────────────┤
│ feishu          │ ✅ 已配置 │ 远程 MCP，自动 OAuth           │
│ feishu-official │ ⚠️ 待授权 │ 需手动 OAuth 授权            │
└─────────────────┴──────────┴────────────────────────────────┘

详细说明:
- feishu: 通过 /mcp → feishu → Authentication 完成授权
- feishu-official: 需要先获取 UAT Token

[刷新 Token] [重新检测] [查看帮助]

配置 MCP

场景 1: 添加 feishu MCP

如果 .mcp.json 中没有 feishu 配置：

是否添加 feishu MCP？

feishu MCP 提供完整的飞书能力：
- 文档/知识库操作
- 多维表格操作
- 日历/任务管理
- 消息发送

[添加] [跳过]

如果选择添加，生成配置并写入 .mcp.json:

{
  "mcpServers": {
    "feishu": {
      "type": "http",
      "url": "https://feishu-mcp.fastgrowth.ai/mcp"
    }
  }
}

场景 2: 添加 feishu-official MCP

如果 .mcp.json 中没有 feishu-official 配置：

是否添加 feishu-official MCP？

feishu-official MCP 提供云文档深度操作：
- search-doc (仅 UAT 可用)
- create-doc, fetch-doc, update-doc
- list-docs, get-comments, add-comments
- 搜索用户等

[添加] [跳过]

如果选择添加，生成配置：

{
  "mcpServers": {
    "feishu": { ... },
    "feishu-official": {
      "type": "http",
      "url": "https://mcp.feishu.cn/mcp",
      "headers": {
        "X-Lark-MCP-UAT": "${FEISHU_UAT}",
        "X-Lark-MCP-Allowed-Tools": "search-doc,create-doc,fetch-doc,update-doc,list-docs,get-comments,add-comments,search-user,get-user,fetch-file"
      }
    }
  }
}

授权流程

feishu MCP 授权

飞书授权流程 (feishu)

1. 在 Claude Code 中输入 /mcp
2. 选择 feishu MCP 服务器
3. 按 Enter 进入后，选择 Authentication
4. 浏览器自动打开授权页面
5. 在网页上点击授权

授权完成后，飞书工具即可使用。

feishu-official MCP 授权

此 MCP 使用 UAT Token，需要通过 OAuth Device Flow 完成授权。

首次授权

Step 1: 启动授权流程

调用以下 API 获取授权码：

curl -X POST 'https://accounts.feishu.cn/oauth/v1/device_authorization' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'client_id=cli_a924f4657d389bd7&client_secret=DJkvBSsQpDIe0cXJ6nki7csoBlxeqvqd&scope=docx:document:readonly docx:document:create docx:document:write_only wiki:node:read wiki:node:create wiki:wiki:readonly search:docs:read contact:user.base:readonly contact:user:search'

返回示例：

{
  "device_code": "Ox...",
  "user_code": "XXXX-XXXX",
  "verification_uri": "https://accounts.feishu.cn/oauth/v1/device/verify?flow_id=...",
  "verification_uri_complete": "https://accounts.feishu.cn/oauth/v1/device/verify?flow_id=...&user_code=XXXX-XXXX",
  "expires_in": 180,
  "interval": 5
}

Step 2: 用户完成授权

告诉用户：

Step 3: 轮询获取 Token

用户完成授权后，调用：

curl -X POST 'https://open.feishu.cn/open-apis/authen/v2/oauth/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=urn:ietf:params:oauth:grant-type:device_code&client_id=cli_a924f4657d389bd7&client_secret=DJkvBSsQpDIe0cXJ6nki7csoBlxeqvqd&device_code={device_code}'

成功返回：

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "...",
  "scope": "..."
}

1. 打开浏览器访问:
   {verification_uri_complete}

2. 输入验证码: {user_code}

3. 完成飞书登录和授权

Step 4: 测试连接

用获取的 access_token 测试 MCP：

curl -X POST 'https://mcp.feishu.cn/mcp' \
  -H 'Content-Type: application/json' \
  -H 'X-Lark-MCP-UAT: {access_token}' \
  -H 'X-Lark-MCP-Allowed-Tools: search-doc,fetch-doc,create-doc,list-docs,get-user,search-user' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize"}'

成功响应：

{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-03-26","serverInfo":{"name":"AI friendly MCP Server","version":"1.0.0"}}}

刷新 Token

当 UAT 过期时（有效期约 2 小时），用 refresh_token 续期：

curl -X POST 'https://open.feishu.cn/open-apis/authen/v1/refresh_access_token' \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "存储的refresh_token",
    "client_id": "cli_a924f4657d389bd7",
    "client_secret": "DJkvBSsQpDIe0cXJ6nki7csoBlxeqvqd"
  }'

Token 管理

存储位置

Token 存储在工作空间本地目录，不提交版本控制（会自动添加到 .gitignore）：

• 路径: .claude/feishu/uat.json
• 结构: 同时包含 UAT 和 refresh_token

格式

{
  "feishu-official": {
    "uat": "u-xxxxx",
    "refresh_token": "r-xxxxx",
    "expires_at": "2026-03-12T15:00:00Z",
    "created_at": "2026-03-12T13:00:00Z"
  }
}

自动刷新

启动 Claude Code 时自动检查 UAT 有效性，过期则自动刷新。

问题诊断

常用命令

• "检查飞书状态" - 检测两个 MCP 的状态
• "连接飞书" - 配置飞书 MCP
• "刷新飞书 token" - 刷新 feishu-official 的 UAT
• "飞书授权" - 引导完成 OAuth 授权