# 飞书 MCP Server

让 Claude Code 以**你的身份**直接操作飞书——创建文档、写入内容、发送消息、调用任意飞书 API。

## 原理

```
你说"帮我写飞书文档" → Claude → MCP Server → 飞书 API（你的身份）
                                              ↑
                               OAuth 2.0 User Access Token
```

不是用"机器人"身份，而是通过 OAuth 授权拿到你的用户 Token，飞书看到的所有操作都是**你本人**做的。

## 准备工作

### 1. 创建飞书应用

1. 打开 [飞书开放平台](https://open.feishu.cn)，进入**开发者后台**
2. 创建 **企业自建应用**
3. 在 **凭证与基础信息** 中记录 `App ID` 和 `App Secret`

### 2. 配置权限

进入应用的 **权限管理**，添加以下权限：

- `docx:document` — 文档读写
- `docx:document:readonly` — 文档读取
- `drive:drive` — 云空间操作

### 3. 配置 OAuth 重定向 URL

进入 **安全设置** → 重定向 URL，添加：

```
http://localhost:3040/callback
```

### 4. 发布应用

在 **应用发布** 中创建版本并发布（管理员审批后生效）。

---

## 安装

```bash
# 1. 克隆项目
git clone <repo-url>
cd feishu-mcp-server

# 2. 安装依赖
npm install

# 3. 配置凭证
cp .env.example .env
# 编辑 .env，填入 App ID 和 App Secret
```

## 授权

```bash
node auth.js
```

浏览器会自动打开飞书授权页 → 点「确认授权」→ `refresh_token` 自动写入 `.env`。

## 配置 Claude Code

编辑 **用户级** settings.json（`~/.claude/settings.json` 或 `C:\Users\<用户名>\.claude\settings.json`）：

```json
{
  "mcpServers": {
    "feishu": {
      "command": "node",
      "args": ["<项目路径>/index.js"]
    }
  }
}
```

> 用户级配置让所有项目共用，不需要每个项目重复配。

重启 Claude Code 后生效。

---

## 使用

### 通过 Claude Code（对话）

```
"帮我在飞书创建一个名为「周会纪要」的文档"
"把下面这段分析写到飞书文档 xxx 末尾"
"读取飞书文档 xxx 的内容，帮我总结一下"
```

### 通过命令行（独立使用）

```bash
# 创建一个能被 Claude 读写的文档
node create-doc.js "文档标题"
```

---

## 可用工具

| 工具 | 说明 |
|------|------|
| `feishu_create_document` | 创建新文档 |
| `feishu_write_document_content` | 写入内容（支持 Markdown） |
| `feishu_get_document` | 读取文档 |
| `feishu_send_message` | 发送消息 |
| `feishu_call_api` | 调用任意飞书 API |

## 文件结构

```
├── index.js          # MCP Server 主程序
├── auth.js           # OAuth 授权脚本（首次运行一次）
├── create-doc.js     # 命令行创建文档工具
├── .env.example      # 凭证模板
├── .env              # 真实凭证（不提交 Git）
└── .gitignore

---

# Feishu MCP Server (English)

Let Claude Code operate Feishu/Lark **as you** — create documents, write content, send messages, call any Feishu API.

## How It Works

```
You: "Create a doc in Feishu" → Claude → MCP Server → Feishu API (your identity)
                                                     ↑
                                          OAuth 2.0 User Access Token
```

Instead of a bot identity, the server uses OAuth to obtain a **user access token**. Every action appears in Feishu as done by **you personally** — so you can see and edit everything.

## Prerequisites

### 1. Create a Feishu App

1. Go to [Feishu Open Platform](https://open.feishu.cn) → Developer Console
2. Create an **Enterprise Internal App**
3. Note the `App ID` and `App Secret` from **Credentials & Basic Info**

### 2. Configure Permissions

Navigate to **Permission Management** and add:

- `docx:document` — Read & write documents
- `docx:document:readonly` — Read documents
- `drive:drive` — Cloud drive operations

### 3. Configure OAuth Redirect URL

Go to **Security Settings** → Redirect URL, add:

```
http://localhost:3040/callback
```

### 4. Publish the App

Create a version under **App Publish** and submit for admin approval.

---

## Installation

```bash
git clone <repo-url>
cd feishu-mcp-server
npm install
cp .env.example .env
# Edit .env with your App ID and App Secret
```

## Authorization

```bash
node auth.js
```

A browser window opens → authorize the app → `refresh_token` is saved to `.env` automatically.

---

## Configure Claude Code

Edit your **user-level** `settings.json` (`~/.claude/settings.json` on macOS/Linux, or `C:\Users\<username>\.claude\settings.json` on Windows):

```json
{
  "mcpServers": {
    "feishu": {
      "command": "node",
      "args": ["<path-to-project>/index.js"]
    }
  }
}
```

> User-level config means it works across all projects. Restart Claude Code to load.

---

## Usage

### Via Claude Code

```
"Create a new doc in Feishu called 'Meeting Notes'"
"Append this analysis to Feishu doc xxx"
"Read Feishu doc xxx and summarize it"
```

### Command Line

```bash
# Create a doc that Claude can read & write
node create-doc.js "Document Title"
```

---

## Tools

| Tool | Description |
|------|-------------|
| `feishu_create_document` | Create a new document |
| `feishu_write_document_content` | Write content (supports Markdown) |
| `feishu_get_document` | Read a document |
| `feishu_send_message` | Send a message to a user or chat |
| `feishu_call_api` | Call any Feishu API directly |

## File Structure

```
├── index.js          # MCP Server entry point
├── auth.js           # OAuth authorization script (run once)
├── create-doc.js     # CLI document creation tool
├── .env.example      # Credential template
├── .env              # Real credentials (gitignored)
└── .gitignore
```

## License

MIT
```