飞书 MCP 工具

飞书 MCP 工具是一个基于 Model Context Protocol (MCP) 的服务器，为 AI 工具（如 Cursor、Claude Desktop、Windsurf 等）提供访问飞书文档的能力。

当 AI 工具能够访问飞书文档数据时，它可以更准确地理解和处理文档内容，比其他方法（如复制粘贴文本）更加高效。

✨ 功能特性

📁 文档空间管理

• 列出所有可用的飞书文档空间
• 获取空间基本信息

📄 文档列表管理

• 获取指定空间的文档列表
• 获取所有空间的文档列表
• 支持文档类型过滤

📋 文档信息获取

• 获取文档基本信息：标题、版本、创建时间、修改时间、所有者等
• 获取文档区块结构：完整的文档层级结构，包括所有区块的 ID、类型和层级关系
• 获取特定区块内容：获取指定区块的详细内容和格式信息
• 获取文档纯文本：提取文档的完整纯文本内容，便于 AI 分析和处理

🔗 URL 支持

• 支持飞书文档 URL 自动解析
• 兼容多种飞书文档链接格式

🚀 快速开始

安装

# 从npmjs安装（推荐）
npm install feishu-mcp-tool

# 或使用yarn
yarn add feishu-mcp-tool

# 或使用pnpm
pnpm add feishu-mcp-tool

# 全局安装
npm install -g feishu-mcp-tool

# 从私有仓库安装
npm install feishu-mcp-tool --registry http://your-verdaccio-server:4873

配置飞书应用

1. 访问 飞书开放平台
2. 创建企业自建应用
3. 获取 App ID 和 App Secret
4. 配置应用权限：
   • docx:document:readonly - 文档读取权限
   • wiki:wiki:readonly - 知识库读取权限

环境配置

创建 .env 文件：

FEISHU_APP_ID=your_app_id
FEISHU_APP_SECRET=your_app_secret
PORT=7777

📖 使用方法

作为 MCP 服务器运行（推荐）

# MCP客户端模式（stdio）- 用于AI工具集成
npx feishu-mcp-tool

# 或者全局安装后运行
npm install -g feishu-mcp-tool
feishu-mcp

作为 HTTP 服务器运行

# HTTP服务器模式 - 用于Web访问
npx feishu-mcp-tool --http

# 或使用专用命令
npx feishu-mcp-http

# 或设置环境变量
MCP_HTTP_MODE=true npx feishu-mcp-tool

作为模块使用

import { FeishuMcpServer } from 'feishu-mcp-tool';

// 创建服务器实例
const server = new FeishuMcpServer(
  process.env.FEISHU_APP_ID,
  process.env.FEISHU_APP_SECRET
);

// 启动HTTP服务器
await server.startHttp(7777);

// 或启动标准输入输出模式（用于MCP客户端）
await server.startStdio();

与 AI 工具集成

Cursor 配置

在 Cursor 的设置中添加 MCP 服务器：

{
  "mcpServers": {
    "feishu-mcp": {
      "command": "npx",
      "args": ["feishu-mcp-tool"],
      "env": {
        "FEISHU_APP_ID": "your_app_id",
        "FEISHU_APP_SECRET": "your_app_secret"
      }
    }
  }
}

Claude Desktop 配置

在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "feishu-mcp": {
      "command": "npx",
      "args": ["feishu-mcp-tool"],
      "env": {
        "FEISHU_APP_ID": "your_app_id",
        "FEISHU_APP_SECRET": "your_app_secret"
      }
    }
  }
}

Windsurf 配置

在 Windsurf 的 MCP 设置中添加：

{
  "mcpServers": {
    "feishu-mcp": {
      "command": "npx",
      "args": ["feishu-mcp-tool"],
      "env": {
        "FEISHU_APP_ID": "your_app_id",
        "FEISHU_APP_SECRET": "your_app_secret"
      }
    }
  }
}

🛠️ 可用工具

文档空间工具

list-spaces

列出所有可用的飞书文档空间

参数：无

返回：

{
  "spaces": [
    {
      "id": "space_id",
      "name": "空间名称"
    }
  ]
}

文档列表工具

list-documents

获取指定空间或所有空间的文档列表

参数：

• spaceId (可选): 空间 ID，不提供则返回所有空间的文档

返回：

{
  "documents": [
    {
      "id": "document_id",
      "name": "文档标题",
      "type": "文档类型",
      "spaceId": "space_id",
      "spaceName": "空间名称"
    }
  ]
}

文档信息工具

get-document-info

获取文档基本信息（标题、版本等）

参数：

• documentId: 文档 ID 或 URL

返回：

{
  "document": {
    "document_id": "文档ID",
    "title": "文档标题",
    "revision": 版本号,
    "create_time": "创建时间",
    "edit_time": "修改时间",
    "owner_id": "所有者ID"
  }
}

get-document-blocks

获取文档区块结构和层级

参数：

• documentId: 文档 ID 或 URL
• pageSize (可选): 每页区块数量，默认为 500

返回：

{
  "blocks": [
    {
      "block_id": "区块ID",
      "block_type": "区块类型",
      "parent_id": "父区块ID",
      "children": ["子区块ID列表"]
    }
  ]
}

get-block-content

获取特定区块的详细内容

参数：

• documentId: 文档 ID 或 URL
• blockId: 区块 ID

返回：

{
  "block_id": "区块ID",
  "block_type": "区块类型",
  "parent_id": "父区块ID",
  "content": "区块内容详情"
}

get-document-content

获取文档纯文本内容

参数：

• documentId: 文档 ID 或 URL
• lang (可选): 语言代码，0 为中文，1 为英文，默认为 0

返回：文档的纯文本内容

🔧 开发

本地开发

# 克隆项目
git clone <repository-url>
cd feishu-mcp-tool

# 安装依赖
npm install

# 配置环境变量
cp .env.example .env
# 编辑 .env 文件，填入你的飞书应用凭证

# 启动开发服务器
npm run dev

构建

# 构建项目
npm run build

# 清理构建文件
npm run clean

发布

# 发布到npmjs公共仓库
npm run publish:npmjs

# 发布到私有仓库
npm run publish:verdaccio

# 手动发布到npmjs
npm publish --access public

📝 示例用法

基本使用示例

import { FeishuMcpServer } from 'feishu-mcp-tool';

async function example() {
  // 创建服务器实例
  const server = new FeishuMcpServer('your_app_id', 'your_app_secret');

  // 启动服务器
  await server.startHttp(7777);
  console.log('飞书MCP服务器已启动在端口7777');
}

example().catch(console.error);

在 AI 工具中的使用场景

1. 文档内容分析：AI 可以获取飞书文档的完整内容进行分析
2. 文档结构理解：通过区块结构了解文档的层级关系
3. 批量文档处理：遍历空间中的所有文档进行批量操作
4. 文档信息提取：获取文档的元数据信息

🚨 注意事项

权限要求

确保你的飞书应用具有以下权限：

• docx:document:readonly - 读取文档内容
• wiki:wiki:readonly - 读取知识库内容

安全建议

1. 环境变量：永远不要在代码中硬编码应用凭证
2. 权限最小化：只申请必要的 API 权限
3. 网络安全：在生产环境中使用 HTTPS
4. 访问控制：限制服务器的访问来源

性能优化

1. 分页处理：对于大量文档，使用分页获取
2. 缓存策略：考虑缓存频繁访问的文档内容
3. 并发控制：避免同时发起过多 API 请求

🐛 故障排除

常见问题

1. 认证失败

错误: 获取飞书Token失败

解决方案：

• 检查 FEISHU_APP_ID 和 FEISHU_APP_SECRET 是否正确
• 确认应用状态是否正常

2. 权限不足

错误: API权限不足

解决方案：

• 检查应用是否具有必要的权限
• 确认应用是否已发布并启用

3. 文档访问失败

错误: 无权访问文档

解决方案：

• 确认文档是否存在
• 检查应用是否有访问该文档的权限
• 验证文档 ID 格式是否正确

4. MCP 连接超时

错误: MCP error -2: Request timed out

解决方案：

• 确保环境变量已正确设置（FEISHU_APP_ID, FEISHU_APP_SECRET）
• 检查网络连接是否正常
• 验证飞书应用凭证是否有效
• 确保使用的是 stdio 模式而不是 HTTP 模式

5. 环境变量未设置

错误: 请设置环境变量 FEISHU_APP_ID 和 FEISHU_APP_SECRET

解决方案：

• 创建.env文件并设置正确的值
• 或在 MCP 客户端配置中直接设置环境变量

调试模式

启用详细日志：

DEBUG=feishu-mcp:* npm start

🤝 贡献

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🔗 相关链接

• 飞书开放平台
• Model Context Protocol
• 飞书 API 文档

📞 支持

如果你遇到问题或有建议，请：

1. 查看 FAQ
2. 搜索现有的 Issues
3. 创建新的 Issue

Made with ❤️ for the AI community