Lark Sheet MCP

Lark Sheet MCP服务器

用于访问Feishu/Lark电子表格数据的模型上下文协议（MCP）服务器。在PyPI上可用，便于安装和MCP集成。

快速开始

1. 安装软件包:

   pip install lark-sheet-mcp

1. 添加到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：使用紫外线

   {
     "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"]
       }
     }
   }

1. 开始使用：软件包将在需要时自动安装（方法1-2）或使用预安装版本（方法3）！

概述

该MCP服务器为AI助手提供了通过标准化界面读取和查询飞雀电子表格数据的能力。它支持列出电子表格、读取单元格区域、搜索内容和检索工作表信息等操作。

特性

• 列出电子表格：从用户的Feishu帐户获取可访问的电子表格
• 工作表信息：检索工作表详细信息，包括结构和元数据
• 范围读数：使用各种格式选项读取单个或多个单元格区域
• 单元格搜索：使用正则表达式支持查找符合特定条件的单元格
• 错误处理：具有针对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

开发设置

# Clone the repository
git clone https://github.com/LupinLin1/lark-sheet-mcp.git
cd lark-sheet-mcp

# Install in development mode
pip install -e .

# Install development dependencies
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

用法

运行服务器

# Using environment variables
lark-sheet-mcp

# Using command line arguments
lark-sheet-mcp --app-id your_app_id --app-secret your_app_secret

# With custom log level
lark-sheet-mcp --log-level DEBUG

# Generate sample configuration file
lark-sheet-mcp --create-config config.json

配置选项

可用的MCP工具

1.列表_预表

从您的Feishu帐户获取可访问的电子表格列表。

参数：

• folder_token （可选）：文件夹标记，用于列出特定文件夹中的电子表格
• page_size （可选）：每页的电子表格数量（默认值：50，最大值：200）

示例响应：

[
  {
    "token": "shtxxxxx",
    "name": "My Spreadsheet",
    "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 （必填）：电子表格的令牌

示例响应：

[
  {
    "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 （必填）：电子表格的令牌
• range_spec （必填）：范围规格（例如，“表1！A1:B10”）
• value_render_option （可选）：如何呈现值（“ToString”、“Formula”、“FormattedValue”、“UnformattedValue”）
• date_time_render_option （可选）：如何呈现日期（“FormattedString”）

示例响应：

{
  "range": "Sheet1!A1:B2",
  "major_dimension": "ROWS",
  "values": [
    ["Name", "Age"],
    ["John", "25"]
  ],
  "revision": 12345
}

4.读取多个范围

批量从多个单元格区域读取数据。

参数：

• spreadsheet_token （必填）：电子表格的令牌
• ranges （必填）：量程规格列表（最多100个量程）
• value_render_option （可选）：如何渲染值
• date_time_render_option （可选）：如何呈现日期

示例响应：

[
  {
    "range": "Sheet1!A1:B2",
    "major_dimension": "ROWS",
    "values": [["Name", "Age"], ["John", "25"]],
    "revision": 12345
  },
  {
    "range": "Sheet1!C1:D2", 
    "major_dimension": "ROWS",
    "values": [["City", "Country"], ["NYC", "USA"]],
    "revision": 12345
  }
]

5.find_cells

在一定范围内搜索符合特定条件的单元格。

参数：

• spreadsheet_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 not found 解决方案:

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

问题: 1310213 - Permission denied 解决方案:

• 验证应用程序是否具有所需的权限(spreadsheets:read, drive:read)
• 检查用户是否有权访问所请求的电子表格
• 确保电子表格令牌正确

速率限制

问题: 1310217 - Rate limit exceeded 解决方案:

• 服务器以指数回退方式自动重试
• 如果持续存在，请降低请求频率
• 检查速率限制器配置

数据问题

问题: 1310218 - Data size limit exceeded\ 解决方案:

• 减小范围大小（Feishu每个请求的限制为10MB）
• 使用 read_multiple_ranges 分割大范围
• 考虑对大型数据集进行分页

问题: 1310216 - Invalid range format 解决方案:

• 使用正确的范围格式： 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： 我如何获得电子表格令牌？

A： 使用 list_spreadsheets 该工具用于获取可访问电子表格的令牌，或从Feishu电子表格URL中提取。

Q： 我可以读取的最大数据量是多少？

A： Feishu API的每个请求限制为10MB。如果超过此限制，服务器将返回错误。

Q： 我可以将数据写入电子表格吗？

A： 此服务器当前仅支持读取操作。出于安全原因，不执行写入操作。

Q： 如何处理身份验证令牌？

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

Q： 如果我超过了费率限制，会发生什么？

A： 服务器实现了指数回退的自动重试。您不需要手动处理速率限制。

Q： 我可以将其用于国际飞树/百灵鸟实例吗？

A： 是的，服务器使用国际通用的飞舒开放平台API。

发展

运行测试

# Run all tests
pytest

# Run with coverage
pytest --cov=feishu_spreadsheet_mcp --cov-report=html

# Run specific test file
pytest tests/test_data_models.py

代码质量

# Format code
black feishu_spreadsheet_mcp tests

# Sort imports
isort feishu_spreadsheet_mcp tests

# Lint code
flake8 feishu_spreadsheet_mcp tests

# Type checking
mypy feishu_spreadsheet_mcp

项目结构

feishu_spreadsheet_mcp/
├── __init__.py
├── main.py              # Entry point
├── server.py            # MCP server implementation
├── models/              # Data models
│   ├── __init__.py
│   └── data_models.py
├── services/            # Business logic
│   ├── __init__.py
│   ├── auth_manager.py  # Authentication management
│   └── api_client.py    # Feishu API client
└── tools/               # MCP tools
    ├── __init__.py
    └── spreadsheet_tools.py

许可证

MIT许可证

贡献

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