# feishu-scenarios-mcp

AI-native business operations MCP server for Feishu/Lark. 8 scenario-based tools covering multidimensional tables (Bitable) and approvals — search, query, write, create, AI schema design, approval tracking, alerts, and statistics.

## Installation

```bash
npm install -g feishu-scenarios-mcp
```

Or run directly:

```bash
npx feishu-scenarios-mcp
```

## Configuration

Create a `.env` file with your Feishu app credentials:

```env
FEISHU_APP_ID=cli_xxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxx
FEISHU_BITABLE_APP_TOKEN=xxxxxxxxxxxx
FEISHU_ENV=feishu
```

| Variable | Required | Description |
|----------|----------|-------------|
| `FEISHU_APP_ID` | Yes | Feishu app ID from Developer Console |
| `FEISHU_APP_SECRET` | Yes | Feishu app secret |
| `FEISHU_BITABLE_APP_TOKEN` | For bitable | Bitable app token |
| `FEISHU_ENV` | No | `feishu` (default) or `lark` |
| `FEISHU_USER_ID` | For approval | Your Feishu user open_id |
| `DEEPSEEK_API_KEY` | For schema AI | DeepSeek API key for AI table design |

## Claude Desktop Setup

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "feishu-scenarios": {
      "command": "npx",
      "args": ["-y", "feishu-scenarios-mcp"],
      "env": {
        "FEISHU_APP_ID": "cli_xxxxxxxxxxxx",
        "FEISHU_APP_SECRET": "xxxxxxxxxxxxxxxx",
        "FEISHU_BITABLE_APP_TOKEN": "xxxxxxxxxxxx",
        "FEISHU_ENV": "feishu"
      }
    }
  }
}
```

## Tools

### Bitable (多维表格)

| Tool | Description |
|------|-------------|
| `bitable_search` | Search tables by keyword. Returns table ID, name, field preview, record count. |
| `bitable_query` | Query records with optional filters. |
| `bitable_upsert` | Batch write records. Auto field-name matching and type conversion. |
| `bitable_create` | Create a new table with field definitions. |
| `bitable_schema_ai` | AI-designed table schema from business description. Requires `DEEPSEEK_API_KEY`. |

### Approval (审批)

| Tool | Description |
|------|-------------|
| `approval_list` | Query approval instances by status, type, applicant, time range. |
| `approval_alerts` | Find bottlenecks and overtime approvals. Default threshold 48h. |
| `approval_stats` | Approval statistics: by status, type, month, top applicants. |

## Usage Examples

**Search tables:**
> "搜一下包含'审批'的表格"

**Query records:**
> "查一下积压跟踪表里 pending 状态的记录"

**Write records:**
> "往跟踪表写一条记录，负责人张三，状态待处理"

**AI design table:**
> "帮我设计一张跟踪审批积压的表"

**Approval alerts:**
> "谁审批最慢"

**Approval statistics:**
> "本月审批通过率"

## Feishu Bot (Mobile)

The package also includes a WebSocket-based Feishu bot for mobile access:

```bash
npx feishu-scenarios-mcp-bot
```

Setup guide: [docs/bot-setup.md](docs/bot-setup.md)

## Required Feishu Permissions

- `approval:instance` — read approval instances
- `bitable:app` — access bitable
- `im:message` — bot messaging
- `im:message:send_as_bot` — send bot messages

## License

MIT