Feishu MCP Server

# 飞书MCP服务器 飞书（Feishu）MCP服务器 - 提供多维表格和电子表格的MCP工具 ## 功能特性 - ✅ 自动token管理（2小时有效期自动刷新） - ✅ 多维表格完整支持（10个工具） - ✅ 所有参数使用JSON字符串格式 - ✅ 统一错误处理 - ✅ JSON格式响应 ## 已实现功能 ### 多维表格（Bitable） **应用管理**： - 创建多维表格应用 - 复制多维表格应用 **数据表操作**： - 创建数据表 **记录操作**： - 创建/更新/查询记录 - 批量创建/更新/获取/删除记录 - 支持分页查询 ### 电子表格（Sheets） 待实现（计划17个工具） ## 安装 ### 1. 克隆项目 ```bash git clone <repository-url> cd yuppie-mcp-feishu ``` ### 2. 配置环境变量 复制环境变量模板： ```bash cp .env.example .env ``` 编辑 `.env` 文件，填入你的飞书应用凭证： ```bash FEISHU_APP_ID=cli_xxxxxxxxxxxxx FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxx ``` ### 3. 安装依赖 ```bash uv sync ``` ## 使用 ### 测试运行 ```bash uv run python test_mcp.py ``` ### 作为MCP服务器运行 ```bash uv run yuppie-mcp-feishu ``` 或使用模块方式： ```bash uv run python -m yuppie_mcp_feishu ``` ## Claude Desktop配置 在Claude Desktop配置文件中添加： **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` **Linux**: `~/.config/Claude/claude_desktop_config.json` ```json { "mcpServers": { "feishu": { "command": "/path/to/yuppie-mcp-feishu/.venv/bin/python", "args": ["-m", "yuppie_mcp_feishu"], "env": { "FEISHU_APP_ID": "cli_xxxxxxxxxxxxx", "FEISHU_APP_SECRET": "xxxxxxxxxxxxxxxxxxxx" } } } } ``` 注意：将 `/path/to/yuppie-mcp-feishu` 替换为实际项目路径。 ## 可用工具 所有复杂参数（对象、数组）均使用 **JSON 字符串** 格式传递，以避免 MCP 协议序列化问题。 ### 多维表格数据表 #### `create_bitable_table` 创建数据表 **参数**： - `app_token` (string): 多维表格的app_token - `table_name` (string): 数据表名称 - `fields` (JSON string, 可选): 字段定义列表，例如: `[{"type":1,"name":"字段名"}]` **返回**：JSON格式的数据表信息 ### 多维表格应用 #### `create_bitable_app` 创建新的多维表格应用 **参数**： - `name` (string): 多维表格名称 - `folder_token` (string, 可选): 文件夹token **返回**：JSON格式的应用信息 #### `copy_bitable_app` 复制多维表格应用 **参数**： - `app_token` (string): 要复制的应用token - `name` (string): 新应用名称 - `folder_token` (string, 可选): 文件夹token **返回**：JSON格式的应用信息 ### 多维表格记录 #### `create_bitable_record` 创建单条记录 **参数**： - `app_token` (string): 多维表格token - `table_id` (string): 数据表ID - `fields` (JSON string): 记录字段，例如: `{"字段名":"值"}` #### `update_bitable_record` 更新单条记录 **参数**： - `app_token` (string): 多维表格token - `table_id` (string): 数据表ID - `record_id` (string): 记录ID - `fields` (JSON string): 要更新的字段，例如: `{"字段名":"新值"}` #### `search_bitable_records` 查询记录（支持分页） **参数**： - `app_token` (string): 多维表格token - `table_id` (string): 数据表ID - `page_size` (int, 可选): 每页记录数（1-500） - `page_token` (string, 可选): 分页token - `filter` (JSON string, 可选): 过滤条件，例如: `{"conjunction":"and","conditions":[...]}` #### `batch_create_bitable_records` 批量创建记录（最多1000条） **参数**： - `app_token` (string): 多维表格token - `table_id` (string): 数据表ID - `records` (JSON string): 记录列表，例如: `[{"fields":{"字段名":"值"}}]` #### `batch_update_bitable_records` 批量更新记录（最多1000条） **参数**： - `app_token` (string): 多维表格token - `table_id` (string): 数据表ID - `records` (JSON string): 记录列表，例如: `[{"record_id":"xxx","fields":{"字段名":"新值"}}]` #### `batch_get_bitable_records` 批量获取记录（最多100条） **参数**： - `app_token` (string): 多维表格token - `table_id` (string): 数据表ID - `record_ids` (JSON string): 记录ID列表，例如: `["id1","id2","id3"]` #### `batch_delete_bitable_records` 批量删除记录 **参数**： - `app_token` (string): 多维表格token - `table_id` (string): 数据表ID - `record_ids` (JSON string): 要删除的记录ID列表，例如: `["id1","id2","id3"]` ## 项目结构 ``` src/yuppie_mcp_feishu/ ├── __init__.py # 主入口点 ├── server.py # MCP 服务器和工具路由 ├── impl.py # 所有 API 实现 ├── config.py # 配置管理 └── client.py # 飞书客户端管理 ``` ## 技术栈 - **Python**: >= 3.10 - **飞书SDK**: lark-oapi >= 1.5.2 - **MCP框架**: mcp >= 1.2.0（官方 MCP SDK） - **包管理**: UV ## 开发 ### 运行测试 本项目使用 **MCP 官方 SDK 测试方法**，通过 MCP 协议测试所有工具。 #### 快速开始 ```bash # 1. 配置测试环境变量 cp .env.example .env # 编辑 .env 文件，添加测试用多维表格的 app_token FEISHU_APP_ID=cli_xxxxxxxxxxxxx FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxx FEISHU_DEFAULT_APP_TOKEN=your_app_token_here # 必需：用于测试的多维表格 # 2. 运行所有测试 PYTHONPATH=src uv run pytest tests/yuppie_mcp_feishu/tools_mcp/ -v # 3. 运行单个测试文件 PYTHONPATH=src uv run pytest tests/yuppie_mcp_feishu/tools_mcp/test_create_bitable_record.py -v ``` #### 测试结构 ``` tests/ ├── conftest.py # MCP fixtures + 共享配置 └── yuppie_mcp_feishu/ └── tools_mcp/ # MCP 协议测试 ├── test_create_bitable_record.py ├── test_update_bitable_record.py ├── test_search_bitable_records.py ├── test_batch_create_bitable_records.py ├── test_batch_update_bitable_records.py ├── test_batch_get_bitable_records.py └── test_batch_delete_bitable_records.py ``` #### 测试特点 - ✅ **使用 MCP 官方 SDK**：通过 `create_connected_server_and_client_session()` 创建测试会话 - ✅ **真实 API 调用**：直接连接飞书 API，无 mock - ✅ **每个工具独立测试**：7个工具，7个测试文件，15个测试用例 - ✅ **参数验证**：每个工具都包含成功场景和参数验证测试 #### 测试命令 ```bash # 运行所有 MCP 测试 PYTHONPATH=src uv run pytest tests/yuppie_mcp_feishu/tools_mcp/ -v # 运行特定工具的测试 PYTHONPATH=src uv run pytest tests/yuppie_mcp_feishu/tools_mcp/test_create_bitable_record.py -v # 运行单个测试用例 PYTHONPATH=src uv run pytest tests/yuppie_mcp_feishu/tools_mcp/test_create_bitable_record.py::TestCreateBitableRecord::test_create_record_empty_fields -v # 显示详细输出 PYTHONPATH=src uv run pytest tests/yuppie_mcp_feishu/tools_mcp/ -vv # 列出所有测试（不执行） PYTHONPATH=src uv run pytest tests/yuppie_mcp_feishu/tools_mcp/ --co -q ``` #### Pytest Fixtures 测试使用 pytest fixtures 自动管理测试数据： ```python # 共享 fixtures（conftest.py） test_config → 测试配置（从 .env 读取） default_app_token → 默认测试应用 app_token test_table_id → 测试数据表 ID（session 级别） test_record_id → 单条测试记录 ID（function 级别） test_record_ids → 批量测试记录 ID（function 级别） # MCP fixtures mcp_server → MCP server 实例 client_session → MCP 客户端会话（已连接） ``` ### 安装依赖 ```bash uv sync ``` ### 添加新依赖 ```bash uv add <package-name> ``` ## 文档 - [更新日志](CHANGELOG.md) - 版本变更历史 - [PyPI 发布指南](PUBLISH_TO_PYPI.md) - 如何发布到 PyPI - [开发指南](CLAUDE.md) - Claude Code 开发指南 ## 参考资料 - [飞书开放平台文档](https://open.feishu.cn/document) - [飞书Python SDK](https://github.com/larksuite/oapi-sdk-python) - [MCP协议文档](https://modelcontextprotocol.io/) - [官方 MCP SDK](https://github.com/modelcontextprotocol/python-sdk) ## 许可证 MIT License ## 贡献 欢迎提交Issue和Pull Request！