技术文档摘要

Lark Sheet MCP Server

这是一个用于访问飞书（Lark）电子表格数据的模型上下文协议（MCP）服务器。该包在 PyPI 上提供，便于安装和 MCP 集成。

快速开始

1. 安装包：

   pip install lark-sheet-mcp
   

2. 添加到你的 MCP 配置（选择一种方法）：

   方法 1：使用 pipx（推荐）

   {
     "mcpServers": {
       "lark-sheet-mcp": {
         "command": "pipx",
         "args": ["run", "lark-sheet-mcp", "--app-id", "your_app_id", "--app-secret", "your_app_secret"]
       }
     }
   }
   

   方法 2：使用 uv

   {
     "mcpServers": {
       "lark-sheet-mcp": {
         "command": "uvx", 
         "args": ["lark-sheet-mcp", "--app-id", "your_app_id", "--app-secret", "your_app_secret"]
       }
     }
   }
   

   方法 3：预安装

   {
     "mcpServers": {
       "lark-sheet-mcp": {
         "command": "lark-sheet-mcp",
         "args": ["--app-id", "your_app_id", "--app-secret", "your_app_secret"]
       }
     }
   }
   

3. 开始使用：当需要时，包会自动安装（方法 1-2），或者使用预安装版本（方法 3）！

概览

此 MCP 服务器为 AI 助手提供了通过标准化接口读取和查询飞书（Lark）电子表格数据的能力。它支持的操作包括列出电子表格、读取单元格范围、搜索内容以及检索工作表信息。

功能

• 列出电子表格：获取用户飞书账户中可访问的电子表格
• 工作表信息：检索工作表详情，包括结构和元数据
• 范围读取：读取单个或多个单元格范围，并具有多种格式选项
• 单元格搜索：根据特定标准查找匹配的单元格，支持正则表达式
• 错误处理：全面的错误处理机制，包括针对 API 速率限制的重试机制

安装

先决条件

• Python 3.8 或更高版本
• 飞书开放平台应用凭证（app_id 和 app_secret）

从 PyPI 安装（推荐）

该包现在可在 PyPI 上获得：

pip install lark-sheet-mcp

从 GitHub 安装

pip install git+https://github.com/LupinLin1/lark-sheet-mcp.git

开发环境设置

# 克隆仓库
git clone https://github.com/LupinLin1/lark-sheet-mcp.git
cd lark-sheet-mcp

# 在开发模式下安装
pip install -e .

# 安装开发依赖
pip install -e ".[dev]"

配置

MCP 客户端配置

由于该包在 PyPI 上可用，您可以在您的 MCP 客户端中进行配置。选择最适合您设置的方法：

选项 A：使用 pipx 自动安装（推荐）

{
  "mcpServers": {
    "lark-sheet-mcp": {
      "command": "pipx",
      "args": ["run", "lark-sheet-mcp", "--app-id", "your_app_id", "--app-secret", "your_app_secret"]
    }
  }
}

选项 B：使用 uv 自动安装

{
  "mcpServers": {
    "lark-sheet-mcp": {
      "command": "uvx",
      "args": ["lark-sheet-mcp", "--app-id", "your_app_id", "--app-secret", "your_app_secret"]
    }
  }
}

选项 C：使用预安装包

{
  "mcpServers": {
    "lark-sheet-mcp": {
      "command": "lark-sheet-mcp", 
      "args": ["--app-id", "your_app_id", "--app-secret", "your_app_secret"]
    }
  }
}

注意：请将 your_app_id 和 your_app_secret 替换为您实际的飞书应用凭证。

参见 mcp-config-example.json 获取完整的配置示例。

环境变量

或者设置以下环境变量：

export FEISHU_APP_ID="your_app_id"
export FEISHU_APP_SECRET="your_app_secret"

命令行参数

或者作为命令行参数传递：

lark-sheet-mcp --app-id your_app_id --app-secret your_app_secret

使用

运行服务器

# 使用环境变量
lark-sheet-mcp

# 使用命令行参数
lark-sheet-mcp --app-id your_app_id --app-secret your_app_secret

# 设置自定义日志级别
lark-sheet-mcp --log-level DEBUG

# 生成示例配置文件
lark-sheet-mcp --create-config config.json

配置选项

选项	环境变量	描述	默认值
--app-id	FEISHU_APP_ID	飞书应用 ID	必填
--app-secret	FEISHU_APP_SECRET	飞书应用密钥	必填
--config	-	配置文件路径	无
--log-level	-	日志级别（DEBUG/INFO/WARNING/ERROR）	INFO
--create-config	-	生成示例配置文件	-

可用的 MCP 工具

1. 列出电子表格

获取您飞书账户中可访问的电子表格列表。

参数：

• folder_token（可选）：指定文件夹的 token，以列出该文件夹中的电子表格
• page_size（可选）：每页的电子表格数量（默认：50，最大：200）

示例响应：

[
  {
    "token": "shtxxxxx",
    "name": "我的电子表格",
    "url": "https://example.com/sheets/shtxxxxx",
    "type": "sheet",
    "created_time": "2023-01-01T00:00:00Z",
    "modified_time": "2023-01-01T00:00:00Z",
    "owner_id": "ou_xxxxx"
  }
]

2. 获取工作表信息

获取特定电子表格的工作表信息。

参数：

• spreadsheet_token（必填）：电子表格的 token

示例响应：

[
  {
    "sheet_id": "sheet1",
    "title": "Sheet1",
    "index": 0,
    "row_count": 1000,
    "column_count": 26,
    "frozen_row_count": 0,
    "frozen_column_count": 0,
    "resource_type": "sheet"
  }
]

3. 读取范围

从特定单元格范围读取数据。

参数：

• spreadsheet_token（必填）：电子表格的 token
• range_spec（必填）：范围规范（例如："Sheet1!A1:B10"）
• value_render_option（可选）：如何呈现值（"ToString", "Formula", "FormattedValue", "UnformattedValue"）
• date_time_render_option（可选）：如何呈现日期（"FormattedString"）

示例响应：

{
  "range": "Sheet1!A1:B2",
  "major_dimension": "ROWS",
  "values": [
    ["姓名", "年龄"],
    ["John", "25"]
  ],
  "revision": 12345
}

4. 批量读取多个范围

批量读取多个单元格范围的数据。

参数：

• spreadsheet_token（必填）：电子表格的 token
• ranges（必填）：范围规范列表（最多 100 个范围）
• value_render_option（可选）：如何呈现值
• date_time_render_option（可选）：如何呈现日期

示例响应：

[
  {
    "range": "Sheet1!A1:B2",
    "major_dimension": "ROWS",
    "values": [["姓名", "年龄"], ["John", "25"]],
    "revision": 12345
  },
  {
    "range": "Sheet1!C1:D2", 
    "major_dimension": "ROWS",
    "values": [["城市", "国家"], ["纽约", "美国"]],
    "revision": 12345
  }
]

5. 查找单元格

在范围内查找符合特定标准的单元格。

参数：

• spreadsheet_token（必填）：电子表格的 token
• sheet_id（必填）：工作表的 ID
• range_spec（必填）：要搜索的范围（例如："A1:Z100"）
• find_text（必填）：要搜索的文本或正则表达式模式
• match_case（可选）：是否区分大小写（默认：false）
• match_entire_cell（可选）：是否匹配整个单元格内容（默认：false）
• search_by_regex（可选）：是否使用正则表达式搜索（默认：false）
• include_formulas（可选）：是否仅搜索公式（默认：false）

示例响应：

{
  "matched_cells": ["A1:A1", "B5:B5"],
  "matched_formula_cells": [],
  "rows_count": 2
}

认证设置

获取飞书应用凭证

1. 访问 飞书开放平台
2. 创建新应用或使用现有应用
3. 从应用设置中获取您的 app_id 和 app_secret
4. 配置应用权限以访问电子表格：
   • spreadsheets:read - 读取电子表格数据
   • drive:read - 访问文件列表

权限要求

应用需要以下 OAuth 范围：

• spreadsheets:read - 读取电子表格内容
• drive:read - 列出文件和文件夹

错误处理

服务器实现了全面的错误处理机制，包括：

• 自动重试针对速率限制和临时失败
• 指数退避针对重试延迟
• 认证刷新当令牌过期时
• 用户友好的错误消息支持中文和英文
• 结构化的错误响应遵循 MCP 协议

常见错误代码：

• 1310213：权限被拒绝
• 1310214：电子表格未找到
• 1310215：工作表未找到
• 1310216：无效的范围格式
• 1310217：超出速率限制
• 1310218：数据大小超出限制

故障排除

常见问题

认证错误

问题：99991663 - 应用未找到 解决方案：

• 验证您的 app_id 和 app_secret 是否正确
• 确保应用存在于飞书开放平台
• 检查凭证是否正确设置在环境变量中

问题：1310213 - 权限被拒绝 解决方案：

• 验证应用是否具有所需的权限（spreadsheets:read，drive:read）
• 检查用户是否有访问请求的电子表格的权限
• 确保电子表格 token 正确

速率限制

问题：1310217 - 超出速率限制 解决方案：

• 服务器会自动重试并采用指数退避
• 如果持续出现，请减少请求频率
• 检查速率限制器配置

数据问题

问题：1310218 - 数据大小超出限制 解决方案：

• 减少范围大小（飞书每个请求有 10MB 的限制）
• 使用 read_multiple_ranges 将大范围拆分
• 对于大数据集考虑分页

问题：1310216 - 无效的范围格式 解决方案：

• 使用正确的范围格式：SheetName!A1:B10
• 确保工作表名称存在于电子表格中
• 检查工作表名称中的特殊字符

调试

启用调试日志以查看详细的请求/响应信息：

lark-sheet-mcp --log-level DEBUG

或者设置环境变量：

export FEISHU_LOG_LEVEL=DEBUG

性能提示

1. 使用批处理操作：read_multiple_ranges 比多次调用 read_range 更高效
2. 限制范围大小：保持范围在 10MB 以内以避免超时
3. 缓存令牌：服务器会自动缓存认证令牌
4. 速率限制：内置的速率限制防止 API 配额耗尽

常见问题

Q: 如何获取电子表格 token？

A: 使用 list_spreadsheets 工具获取可访问电子表格的 token，或从飞书电子表格 URL 中提取。

Q: 最多可以读取多少数据？

A: 飞书 API 每个请求有 10MB 的限制。如果超过此限制，服务器将返回错误。

Q: 我可以向电子表格写入数据吗？

A: 该服务器目前仅支持读取操作。出于安全原因，写入操作尚未实现。

Q: 认证令牌是如何处理的？

A: 服务器会自动管理租户访问令牌，包括刷新和缓存，带有 5 分钟的过期缓冲。

Q: 如果我超出速率限制会发生什么？

A: 服务器会实现自动重试并采用指数退避。您不需要手动处理速率限制。

Q: 我可以与国际飞书/Lark 实例一起使用吗？

A: 是的，该服务器使用标准的飞书开放平台 API，这些 API 支持国际使用。

开发

运行测试

# 运行所有测试
pytest

# 运行覆盖率测试
pytest --cov=feishu_spreadsheet_mcp --cov-report=html

# 运行特定测试文件
pytest tests/test_data_models.py

代码质量

# 格式化代码
black feishu_spreadsheet_mcp tests

# 排序导入
isort feishu_spreadsheet_mcp tests

# 代码检查
flake8 feishu_spreadsheet_mcp tests

# 类型检查
mypy feishu_spreadsheet_mcp

项目结构

feishu_spreadsheet_mcp/
├── __init__.py
├── main.py              # 入口点
├── server.py            # MCP 服务器实现
├── models/              # 数据模型
│   ├── __init__.py
│   └── data_models.py
├── services/            # 业务逻辑
│   ├── __init__.py
│   ├── auth_manager.py  # 认证管理
│   └── api_client.py    # 飞书 API 客户端
└── tools/               # MCP 工具
    ├── __init__.py
    └── spreadsheet_tools.py

许可证

MIT 许可证

贡献

1. 分叉仓库
2. 创建功能分支
3. 进行更改
4. 为新功能添加测试
5. 确保所有测试通过且代码质量检查通过
6. 提交拉取请求