# 飞书MCP服务器

飞书（Feishu）MCP服务器 - 提供多维表格和电子表格的MCP工具

## 功能特性

- ✅ 自动token管理（2小时有效期自动刷新）
- ✅ 多维表格完整支持（9个工具）
- ✅ 统一错误处理
- ✅ 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` 替换为实际项目路径。

## 可用工具

### 多维表格应用

#### `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` (dict): 记录字段

#### `update_bitable_record`
更新单条记录

**参数**：
- `app_token` (string): 多维表格token
- `table_id` (string): 数据表ID
- `record_id` (string): 记录ID
- `fields` (dict): 要更新的字段

#### `search_bitable_records`
查询记录（支持分页）

**参数**：
- `app_token` (string): 多维表格token
- `table_id` (string): 数据表ID
- `page_size` (int, 可选): 每页记录数（1-500）
- `page_token` (string, 可选): 分页token
- `filter` (dict, 可选): 过滤条件

#### `batch_create_bitable_records`
批量创建记录（最多1000条）

**参数**：
- `app_token` (string): 多维表格token
- `table_id` (string): 数据表ID
- `records` (list): 记录列表

#### `batch_update_bitable_records`
批量更新记录（最多1000条）

**参数**：
- `app_token` (string): 多维表格token
- `table_id` (string): 数据表ID
- `records` (list): 记录列表（包含record_id和fields）

#### `batch_get_bitable_records`
批量获取记录（最多100条）

**参数**：
- `app_token` (string): 多维表格token
- `table_id` (string): 数据表ID
- `record_ids` (list): 记录ID列表

#### `batch_delete_bitable_records`
批量删除记录

**参数**：
- `app_token` (string): 多维表格token
- `table_id` (string): 数据表ID
- `record_ids` (list): 要删除的记录ID列表

## 项目结构

```
src/yuppie_mcp_feishu/
├── __init__.py              # 主入口点
├── config.py                # 配置管理
├── client.py                # 飞书客户端管理
├── exceptions.py            # 错误处理
└── tools/
    ├── __init__.py
    ├── bitable_app.py       # 多维表格应用工具
    └── bitable_record.py    # 多维表格记录工具
```

## 技术栈

- **Python**: >= 3.10
- **飞书SDK**: lark-oapi >= 1.5.2
- **MCP框架**: mcp[cli] >= 1.25.0
- **包管理**: UV

## 开发

### 运行测试

```bash
uv run python test_mcp.py
```

### 安装依赖

```bash
uv sync
```

### 添加新依赖

```bash
uv add <package-name>
```

## 参考资料

- [飞书开放平台文档](https://open.feishu.cn/document)
- [飞书Python SDK](https://github.com/larksuite/oapi-sdk-python)
- [MCP协议文档](https://modelcontextprotocol.io/)
- [FastMCP文档](https://gofastmcp.com)

## 许可证

MIT License

## 贡献

欢迎提交Issue和Pull Request！