---
name: happycapy-feishu
description: 为 HappyCapy 安装并授权飞书（Lark）MCP，让 Claude 直接操作飞书消息、文档、多维表格、日历等。当用户提到安装飞书 MCP、配置飞书、接入飞书、飞书 MCP setup、connect feishu/lark、飞书重新授权、飞书 token 过期、lark mcp 失效等场景时，必须使用此 skill。
---

# 飞书 MCP 安装向导

**首先询问用户：** 你是否已经有飞书应用的 **App ID** 和 **App Secret**？

- **有的话**：直接告知你，Claude 立即进入第二步执行安装和 OAuth 授权。
- **没有的话**：按第一步引导用户创建应用。

---

## 第一步：引导用户创建飞书应用（仅在用户没有凭证时执行）

告知用户按以下步骤操作，完成后把 **App ID** 和 **App Secret** 发给你：

1. 打开 https://open.feishu.cn/app 并登录
2. 右上角点击**创建应用** → **自建应用**，填写任意名称（如 `Claude MCP`）
3. 进入应用后，**凭证与基础信息**页面找到 **App ID** 和 **App Secret**
4. 左侧菜单进入**安全设置** → **重定向 URL** → 添加：`http://localhost:3000/callback`
5. 左侧菜单进入**权限管理** → 右上角点击**批量导入权限** → 粘贴以下 JSON 后确认导入：

> **重要：** 每次引导用户时，必须读取 `assets/feishu-permissions.json` 并将其完整内容全量输出，不得省略、截断或用省略号代替任何内容。

6. 左侧菜单进入**添加应用能力** → 务必开启 **机器人** 能力

7. 左侧菜单进入**事件与回调** → **事件配置**：
   - 请求方式选择：**使用长连接接收事件**（无需公网服务器）
   - 点击**添加事件**，搜索 `im.message.receive_v1`（接收消息），勾选添加

8. 左侧菜单进入**版本管理与发布**，创建版本并发布（内部测试版即可）

---

## 第二步：自动安装配置（收到凭证后 Claude 执行）

### 2.1 注册 MCP 到全局配置

直接编辑 `~/.claude.json`，向其中写入 `mcpServers` 字段（保留已有内容）：

```bash
python3 -c "
import json, os
f = os.path.expanduser('~/.claude.json')
with open(f) as fp:
    cfg = json.load(fp)
cfg.setdefault('mcpServers', {})['lark-mcp'] = {
    'command': 'npx',
    'args': ['-y', '@larksuiteoapi/lark-mcp', 'mcp',
             '-a', '<APP_ID>', '-s', '<APP_SECRET>',
             '--oauth',
             '--tools', 'preset.default,im.v1.message.reply,im.v1.message.get,im.v1.message.patch,im.v1.message.delete,im.v1.chat.get,im.v1.chat.search']
}
with open(f, 'w') as fp:
    json.dump(cfg, fp, indent=2, ensure_ascii=False)
print('MCP 注册完成')
"
```

### 2.2 定位 lark-mcp 缓存目录（后续步骤共用）

无桌面 Linux 环境中 keytar 依赖 dbus-launch，导致 token 只存内存、重启即丢失。先触发下载并定位目录：

```bash
# 触发一次确保包已下载
npx -y @larksuiteoapi/lark-mcp --version 2>/dev/null || true

# 定位缓存目录，后续 2.3 和 2.4 共用此变量
LARK_DIR=$(find ~/.npm/_npx -name "package.json" 2>/dev/null \
  | xargs grep -l '"@larksuiteoapi/lark-mcp"' 2>/dev/null \
  | grep -v node_modules | head -1 | xargs dirname)
echo "LARK_DIR: $LARK_DIR"
```

### 2.3 修复 headless 环境 token 持久化（替换 keytar 为文件存储）

使用 skill 内置的预置文件替换 keytar（token 保存在 `~/.lark-mcp-keychain.json`）：

```bash
KEYTAR_PATH="$LARK_DIR/node_modules/keytar/lib/keytar.js"
cp "$KEYTAR_PATH" "${KEYTAR_PATH}.bak"
cp ~/.claude/skills/happycapy-feishu/assets/keytar-file-storage.js "$KEYTAR_PATH"
echo "keytar 替换完成: $KEYTAR_PATH"
```

### 2.4 延长 OAuth 超时至 5 分钟

lark-mcp 有两处独立超时需要同时修改，**必须用 `perl -i` 而非 `sed -i`**（后者在此环境会截断文件）：

```bash
# 修复 handler-local.js（HTTP 服务器超时）
HANDLER="$LARK_DIR/node_modules/@larksuiteoapi/lark-mcp/dist/auth/handler/handler-local.js"
perl -i -pe 's/this\.stopServer\(\), 60 \* 1000/this.stopServer(), 300 * 1000/g' "$HANDLER"

# 修复 login-handler.js（token 轮询超时）
LOGIN_HANDLER="$LARK_DIR/node_modules/@larksuiteoapi/lark-mcp/dist/cli/login-handler.js"
perl -i -pe 's/timeout = 60000/timeout = 300000/g' "$LOGIN_HANDLER"

echo "handler-local: $(grep -o '[0-9]* \* 1000' $HANDLER)"
echo "login-handler: $(grep -o 'timeout = [0-9]*' $LOGIN_HANDLER)"
```

---

## 第三步：OAuth 授权（用户只需做一个操作）

### 3.1 启动 login 进程，获取 code_challenge

```bash
kill $(lsof -ti:3000) 2>/dev/null; sleep 1
nohup npx -y @larksuiteoapi/lark-mcp login \
  -a <APP_ID> -s <APP_SECRET> > /tmp/lark-oauth.log 2>&1 &
sleep 5 && cat /tmp/lark-oauth.log
```

从日志的 Authorization URL 中提取 `code_challenge=` 后面的值。

### 3.2 服务端 curl /authorize（必须执行，存储 PKCE 状态）

> 跳过此步会导致 callback 时报错 `PKCE validation failed: code challenge not found`

```bash
FEISHU_URL=$(curl -s -w "%{redirect_url}" -o /dev/null \
  "http://localhost:3000/authorize?client_id=client_id_for_local_auth&response_type=code&code_challenge=<CODE_CHALLENGE>&code_challenge_method=S256&redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Fcallback&state=reauthorize")
echo "$FEISHU_URL"
```

### 3.3 让用户完成授权

把上一步输出的 `https://open.feishu.cn/...` 链接发给用户，**明确告知以下三点**：

> **第一步：** 在浏览器打开上面的链接，用飞书账号登录并点击授权。
>
> **第二步：** 授权完成后，浏览器会自动跳转到一个以 `http://localhost:3000/callback?code=...` 开头的地址，并显示"无法访问此网站"或"连接被拒绝"的错误页面——**这是完全正常的，不要关闭页面。**
>
> **第三步：** 忽略错误提示，直接复制浏览器地址栏的完整 URL（以 `http://localhost:3000/callback` 开头），粘贴发给我。

### 3.4 收到 callback URL 后立即提交

```bash
curl -s "<用户发来的完整 URL>"
# 返回 "success, you can close this page now" 即成功
```

### 3.5 验证

```bash
npx -y @larksuiteoapi/lark-mcp whoami
```


---
Source attribution: happycapy-ai
Original project: https://github.com/happycapy-ai/Happycapy-skills
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Mega AI Hub.

## Upstream license notice

MIT License

Copyright (c) 2026 HappyCapy Team

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Mega AI Hub resource metadata

Creator / publisher: happycapy-ai
Original project: https://github.com/happycapy-ai/Happycapy-skills
Attribution basis: Original repository namespace preserved by package mirror

Fields of work: Product Management, Sales, Customer Support
Roles: Customer Success Manager, Product Manager, Technical Support
Specialties: API
Tools: Feishu
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 8ad17a4410acac814b960c4802f4f89cb39603074e6b252f262ba29e58922a13
Metadata reviewed: 2026-10-27
This metadata supersedes earlier Mega AI Hub catalog attribution. Original instruction and supporting files are preserved.