README.md
Enables Claude to read Feishu documents, spreadsheets, and multi-dimensional tables.
Feishu MCP Server
让 Claude 读取飞书文档、电子表格和多维表格。
安装
pnpm install
使用
0. 创建飞书应用
前往飞书开放平台创建一个自建应用：
- 登录开放平台，点击「创建自建应用」
- 进入应用，在「权限管理」中开通以下权限：
sheets:spreadsheet:readonly— 读取电子表格docx:document:readonly— 读取文档bitable:app:readonly— 读取多维表格drive:drive:readonly— 读取云空间
- 在「安全设置」中添加重定向 URL：
http://localhost:3000/callback - 在「凭证与基础信息」中获取 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 获取。
Tools (8)
get_document_infoRetrieves metadata for a Feishu document.read_document_contentReads the content of a Feishu document.read_document_blocksReads specific blocks from a Feishu document.get_spreadsheet_infoRetrieves metadata for a Feishu spreadsheet.list_sheetsLists all sheets within a Feishu spreadsheet.read_spreadsheet_rangeReads data from a specific range in a Feishu spreadsheet.list_bitable_tablesLists all tables within a Feishu Bitable (multi-dimensional table).read_bitable_recordsReads records from a Feishu Bitable table.Environment Variables
APP_IDrequiredThe App ID from the Feishu Open PlatformAPP_SECRETrequiredThe App Secret from the Feishu Open PlatformConfiguration
claude_desktop_config.json
{"mcpServers": {"feishu": {"command": "npx", "args": ["tsx", "/absolute/path/to/src/index.ts", "-a", "<APP_ID>", "-s", "<APP_SECRET>"]}}}Try it
→Read the content of the Feishu document at https://feishu.cn/docx/docxxxx and summarize the key action items.
→List all the sheets available in the spreadsheet with token xxxx.
→Fetch the records from the Bitable with app token xxxx and table ID yyyy.
→Extract the data from the range A1:D10 in my Feishu spreadsheet.