npm package: @supermoon/lark-project-mcp
Description: MCP Server for Lark Project (飞书项目) - Read work items, search issues, and more
Latest version: 1.0.0

# lark-project-mcp

[English](#english) | [中文](#中文)

---

## English

MCP Server for Lark Project (飞书项目) - Read work items, search issues, and more in AI assistants.

### Features

| Tool | Description |
|------|-------------|
| `get_work_item_by_url` | Get work item details by URL |
| `get_work_item` | Get work item by project/type/ID |
| `search_work_items` | Search work items |
| `get_projects` | List accessible projects |
| `get_work_item_types` | List work item types in a project |
| `get_workflow` | Get workflow status of a work item |
| `get_comments` | Get comments of a work item |

### Installation

```bash
npm install -g @supermoon/lark-project-mcp
```

### Configuration

#### 1. Get Credentials

1. Visit [Lark Project Open Platform](https://project.feishu.cn)
2. Click avatar (bottom-left) → **Open Platform** → **Create Plugin**
3. Get **Plugin ID** and **Plugin Secret**
4. In **Permission Management**, select data scope and required permissions
5. Double-click your avatar to get **User Key**

Documentation: https://project.feishu.cn/b/helpcenter/1p8d7djs/4id4bvnf

#### 2. Configure MCP

**Claude Code** (`~/.claude/mcp-servers.json`)

```json
{
  "mcpServers": {
    "lark-project": {
      "command": "npx",
      "args": ["-y", "@supermoon/lark-project-mcp"],
      "env": {
        "LARK_PROJECT_PLUGIN_ID": "your_plugin_id",
        "LARK_PROJECT_PLUGIN_SECRET": "your_plugin_secret",
        "LARK_PROJECT_USER_KEY": "your_user_key"
      }
    }
  }
}
```

**Codex CLI** (`~/.codex/config.toml`)

```toml
[mcp_servers."lark-project"]
command = "npx"
args = ["-y", "@supermoon/lark-project-mcp"]
env = { "LARK_PROJECT_PLUGIN_ID" = "your_plugin_id", "LARK_PROJECT_PLUGIN_SECRET" = "your_plugin_secret", "LARK_PROJECT_USER_KEY" = "your_user_key" }
startup_timeout_sec = 60
```

**Generic MCP JSON** (for other MCP-compatible clients)

```json
{
  "lark-project": {
    "command": "npx",
    "args": ["-y", "@supermoon/lark-project-mcp"],
    "env": {
      "LARK_PROJECT_PLUGIN_ID": "your_plugin_id",
      "LARK_PROJECT_PLUGIN_SECRET": "your_plugin_secret",
      "LARK_PROJECT_USER_KEY": "your_user_key"
    }
  }
}
```

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `LARK_PROJECT_PLUGIN_ID` | Yes | Plugin ID |
| `LARK_PROJECT_PLUGIN_SECRET` | Yes | Plugin Secret |
| `LARK_PROJECT_USER_KEY` | Yes | User Key |
| `LARK_PROJECT_BASE_URL` | No | API URL, default `https://project.feishu.cn` |

### Usage Example

After configuration, use in AI assistant:

```
Read this issue https://project.feishu.cn/myproject/issue/detail/123456789
```

---

## 中文

飞书项目 MCP Server - 在 AI 助手中读取飞书项目工单内容。

### 功能

| 工具 | 说明 |
|------|------|
| `get_work_item_by_url` | 根据 URL 获取工作项详情 |
| `get_work_item` | 根据空间/类型/ID 获取工作项 |
| `search_work_items` | 搜索工作项列表 |
| `get_projects` | 获取有权限的空间列表 |
| `get_work_item_types` | 获取空间下的工作项类型 |
| `get_workflow` | 获取工作项的工作流状态 |
| `get_comments` | 获取工作项的评论 |

### 安装

```bash
npm install -g @supermoon/lark-project-mcp
```

### 配置

#### 1. 获取凭证

1. 访问 [飞书项目开放平台](https://project.feishu.cn)
2. 左下角头像 → **开放平台** → **新建插件**
3. 获取 **Plugin ID** 和 **Plugin Secret**
4. 在 **权限管理** 中选择数据范围并勾选所需权限
5. 双击用户头像获取 **User Key**

详细文档: https://project.feishu.cn/b/helpcenter/1p8d7djs/4id4bvnf

#### 2. 配置 MCP

**Claude Code** (`~/.claude/mcp-servers.json`)

```json
{
  "mcpServers": {
    "lark-project": {
      "command": "npx",
      "args": ["-y", "@supermoon/lark-project-mcp"],
      "env": {
        "LARK_PROJECT_PLUGIN_ID": "你的插件ID",
        "LARK_PROJECT_PLUGIN_SECRET": "你的插件密钥",
        "LARK_PROJECT_USER_KEY": "你的用户标识"
      }
    }
  }
}
```

**Codex CLI** (`~/.codex/config.toml`)

```toml
[mcp_servers."lark-project"]
command = "npx"
args = ["-y", "@supermoon/lark-project-mcp"]
env = { "LARK_PROJECT_PLUGIN_ID" = "你的插件ID", "LARK_PROJECT_PLUGIN_SECRET" = "你的插件密钥", "LARK_PROJECT_USER_KEY" = "你的用户标识" }
startup_timeout_sec = 60
```

**通用 MCP JSON 配置** (适用于其他 MCP 兼容客户端)

```json
{
  "lark-project": {
    "command": "npx",
    "args": ["-y", "@supermoon/lark-project-mcp"],
    "env": {
      "LARK_PROJECT_PLUGIN_ID": "你的插件ID",
      "LARK_PROJECT_PLUGIN_SECRET": "你的插件密钥",
      "LARK_PROJECT_USER_KEY": "你的用户标识"
    }
  }
}
```

### 环境变量

| 变量名 | 必需 | 说明 |
|--------|------|------|
| `LARK_PROJECT_PLUGIN_ID` | 是 | 插件 ID |
| `LARK_PROJECT_PLUGIN_SECRET` | 是 | 插件密钥 |
| `LARK_PROJECT_USER_KEY` | 是 | 用户标识 |
| `LARK_PROJECT_BASE_URL` | 否 | API 地址，默认 `https://project.feishu.cn` |

### 使用示例

配置完成后，在 AI 助手中直接使用：

```
读取这个工单 https://project.feishu.cn/myproject/issue/detail/123456789
```

---

## License

MIT