Feishu MCP Server

让 Claude 读取飞书文档、电子表格和多维表格。

安装

pnpm install

使用

0. 创建飞书应用

前往飞书开放平台创建一个自建应用：

1. 登录开放平台，点击「创建自建应用」
2. 进入应用，在「权限管理」中开通以下权限：
   • sheets:spreadsheet:readonly — 读取电子表格
   • docx:document:readonly — 读取文档
   • bitable:app:readonly — 读取多维表格
   • drive:drive:readonly — 读取云空间
3. 在「安全设置」中添加重定向 URL：http://localhost:3000/callback
4. 在「凭证与基础信息」中获取 App ID 和 App Secret

应用需要发布版本后，权限才会生效。如果只在开发环境使用，可以创建测试版本并添加可用性范围。

1. 获取用户令牌

npx tsx src/oauth.ts -a <APP_ID> -s <APP_SECRET>

浏览器会打开飞书授权页面，登录授权后令牌会自动保存到 ~/.feishu-mcp/tokens.json。令牌过期后服务端会自动使用 refresh token 续期。

2. 配置 Claude MCP

在 Claude 的 MCP 配置中添加：

{
  "mcpServers": {
    "feishu": {
      "command": "npx",
      "args": [
        "tsx", "/absolute/path/to/src/index.ts",
        "-a", "<APP_ID>",
        "-s", "<APP_SECRET>"
      ]
    }
  }
}

参数	说明
-a	飞书应用 App ID
-s	飞书应用 App Secret

服务端会自动从 ~/.feishu-mcp/tokens.json 加载用户令牌，无需在配置中写入 -u 和 -r。省略用户令牌则使用 tenant token，只能访问应用本身有权限的资源。

令牌过期

用户令牌有效期约 2 小时，refresh token 有效期约 30 天。服务端会在令牌过期时自动续期。如果 refresh token 也过期，重新运行步骤 1 即可。

可用工具

• get_document_info / read_document_content / read_document_blocks — 读取文档
• get_spreadsheet_info / list_sheets / read_spreadsheet_range — 读取电子表格
• list_bitable_tables / read_bitable_records — 读取多维表格

从 URL 提取 ID

URL 路径	提取内容
feishu.cn/docx/<id>	文档 ID
feishu.cn/sheets/<token>	电子表格 token
feishu.cn/base/<token>	多维表格 app token

凭据安全

• App ID / App Secret：应用级凭据，可通过私密渠道分享给团队成员。勿提交到 git。
• 用户令牌：存储在 ~/.feishu-mcp/tokens.json，个人凭据，每人需自行运行步骤 1 获取。