feishu-connect

name	feishu-connect
description	飞书 MCP 连接管理。在以下场景触发： 1. 用户说 "飞书连接"、"连接飞书"、"飞书配置" 2. 用户说 "飞书状态"、"检查飞书连接" 3. 用户说 "飞书授权"、"授权飞书" 4. 用户说 "飞书 token"、"刷新飞书 token" 5. 会话启动时自动检测飞书 MCP 状态 管理两个飞书 MCP 的连接状态、授权流程和 Token 刷新。

飞书 MCP 连接管理

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

两个飞书 MCP

名称	用途	地址
feishu	日常交互，全功能	https://feishu-mcp.fastgrowth.ai/mcp
feishu-official	云文档深度操作	https://mcp.feishu.cn/mcp

功能列表

功能	描述
状态检测	检测两个 MCP 的配置和授权状态
配置引导	引导用户配置 MCP
授权引导	引导用户完成 OAuth 授权
Token 刷新	刷新官方 MCP 的 UAT Token
问题诊断	检测常见问题并给出解决方案

检测 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 连接失败	网络问题、URL 错误	检查 .mcp.json 配置
授权失败	授权码过期	重新获取授权码
Token 无效	UAT 过期	刷新 Token
工具调用失败	权限不足	检查应用权限配置

常用命令

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