English | 中文
# feishu-inout
**One command to connect your AI coding agent to Lark (Feishu) docs, messaging, calendar & more**
Claude Code / Cursor / Codex / OpenCode / OpenClaw — docs, messaging, calendar, bitable on Lark
[](LICENSE)
[](https://python.org)
[](#)
[](https://mcp.feishu.cn)
---
> **Search, read, create, edit, append, replace, insert, delete, send/read/search messages, calendar, bitable** — do everything with Lark docs, messaging, calendar, and bitable from your AI coding agent.
>
> Built on Lark's official Remote MCP service. Zero dependencies, single file, works out of the box.
## Highlights
- **Search Documents** — by keyword, author, time range
- **7 Edit Modes** — append, overwrite, replace range, replace all, insert before/after, delete — precise edits without data loss
- **One-Step Create** — title + Markdown content in one call, with wiki/folder targeting
- **Full Messaging** — send, read, reply, and search messages across DMs and groups, with Markdown, @mentions, and emoji
- **Zero Dependencies** — pure Python stdlib, no Node.js, no local MCP server
- **Comment Management** — view whole-doc and inline comments, add comments with @mentions
- **User Search** — find colleagues' open_id for @mentions
- **File Access** — download images, attachments, whiteboard content
- **My Library** — browse personal docs without IDs, recursive wiki exploration
- **Paginated Reading** — offset + limit for large documents
- **Calendar & Meetings** — create events with auto video meeting, invite attendees, view today's schedule
- **Bitable (Spreadsheet)** — read, create, update records in multi-dimensional tables
- **Group Management** — create groups, add members, list groups
- **Auto Token Refresh** — OAuth tokens refresh automatically, login once and forget
## Who Is This For?
Not just for developers — anyone who uses Lark/Feishu docs can benefit:
- **Product** — generate PRDs, update requirements, sync release notes
- **Operations** — draft campaign plans, maintain content calendars, update SOPs
- **Data** — write analysis reports directly to docs, auto-format weekly metrics
- **Sales** — create proposals, update client records, generate quotes
- **HR** — draft job descriptions, update onboarding guides, revise policies
If your workflow involves "open Lark → find a doc → edit → notify someone", now it's just one sentence.
## Supported AI Tools
| Claude Code |
Cursor |
Codex |
OpenCode |
OpenClaw |
| Gemini CLI |
GitHub Copilot |
Amp |
Windsurf |
Cline |
| Roo Code |
Clawd |
Trae |
Kiro |
Kilo |
| Goose |
Factory.ai |
Antigravity |
+ any skills-compatible agent |
## Install
```bash
npx skills add joe960913/feishu-inout
```
## Quick Start (5 min)
### 1. Create a Lark App
Go to [Lark Open Platform](https://open.larksuite.com/app) ([China: open.feishu.cn](https://open.feishu.cn/app)) → Create a custom app → Note your **App ID** and **App Secret**
### 2. Enable Permissions
Go to your app → Permission Management → **Batch Import/Export** and paste:
```
docx:document:readonly,search:docs:read,wiki:wiki:readonly,im:chat:read,task:task:read,docx:document,docx:document:create,docx:document:write_only,docs:document.media:upload,docs:document.media:download,wiki:node:read,wiki:node:create,docs:document.comment:read,docs:document.comment:create,contact:user:search,contact:contact.base:readonly,contact:user.base:readonly,board:whiteboard:node:read,drive:drive,im:message,im:message:send_as_bot,im:chat,search:message,im:message.send_as_user,im:message.p2p_msg:get_as_user,im:message.group_msg:get_as_user,calendar:calendar:readonly,calendar:calendar,bitable:app:readonly,bitable:app,im:chat:create
```
Or enable individually (click to expand)
#### Core (required)
| Scope | Description |
|-------|-------------|
| `docx:document:readonly` | View documents |
| `search:docs:read` | Search documents |
| `wiki:wiki:readonly` | View wiki |
| `im:chat:read` | View chat info |
| `task:task:read` | View tasks |
#### Write (for editing)
| Scope | Description |
|-------|-------------|
| `docx:document` | Edit documents |
| `docx:document:create` | Create documents |
| `docx:document:write_only` | Write documents |
| `docs:document.media:upload` | Upload images |
| `wiki:node:read` | View wiki nodes |
| `wiki:node:create` | Create wiki nodes |
#### Comments / Users / Files (optional)
| Scope | Description |
|-------|-------------|
| `docs:document.comment:read` | Read comments |
| `docs:document.comment:create` | Create comments |
| `contact:user:search` | Search users |
| `contact:contact.base:readonly` | Contact info |
| `contact:user.base:readonly` | User info |
| `docs:document.media:download` | Download files |
| `board:whiteboard:node:read` | View whiteboards |
| `drive:drive` | Manage drive files |
#### Messaging (optional)
| Scope | Description |
|-------|-------------|
| `im:message` | Manage messages |
| `im:message:send_as_bot` | Send as bot |
| `im:chat` | Access chat list |
| `search:message` | Search messages |
| `im:message.send_as_user` | Send messages as user |
| `im:message.p2p_msg:get_as_user` | Read DM messages as user |
| `im:message.group_msg:get_as_user` | Read group chat messages as user |
#### Calendar (optional)
| Scope | Description |
|-------|-------------|
| `calendar:calendar:readonly` | View calendar events |
| `calendar:calendar` | Manage calendar events |
#### Bitable (optional)
| Scope | Description |
|-------|-------------|
| `bitable:app:readonly` | View bitable records |
| `bitable:app` | Manage bitable records |
#### Group Management (optional)
| Scope | Description |
|-------|-------------|
| `im:chat:create` | Create group chats |
### 3. Add Redirect URL
App → Security Settings → Redirect URL → Add:
```
http://localhost:9876/callback
```
### 4. Set Environment Variables
Set your credentials (**never share App Secret with AI**):
**macOS / Linux:**
```bash
echo 'export FEISHU_APP_ID="your_app_id"' >> ~/.zshrc
echo 'export FEISHU_APP_SECRET="your_app_secret"' >> ~/.zshrc
source ~/.zshrc
```
**Windows (PowerShell):**
```powershell
[System.Environment]::SetEnvironmentVariable('FEISHU_APP_ID', 'your_app_id', 'User')
[System.Environment]::SetEnvironmentVariable('FEISHU_APP_SECRET', 'your_app_secret', 'User')
# Restart terminal after setting
```
### 5. Login
Tell your AI agent to log in:
```
You: Log in to Lark
AI: Running OAuth login...
Browser opened, please authorize ✓
UAT saved! You can now access your Lark docs.
```
Tokens auto-refresh. No need to log in repeatedly.
### 6. Messaging (no bot required)
Messaging now goes through the official Lark Remote MCP using **your user identity (UAT)** — no bot capability needed. After logging in (Step 5), you can send, read, reply to, and search messages directly as yourself.
> Bot capability is **not required** for messaging. All messages are sent and read under your own Lark identity.
## Usage Examples
After setup, **just talk to your AI agent naturally**:
### Search and Browse
```
You: What Lark docs do I have?
AI: Found 20 documents:
1. Q2 Product Roadmap — Wang Ming (3/25)
2. Frontend Refactor Plan — Li Hua (3/24)
3. Onboarding Guide — Zhang Wei (3/23)
...
```
### Read Documents
```
You: Read this doc https://xxx.larksuite.com/wiki/ABC123def
AI: ## Frontend Refactor Plan
### Goals
- Migrate to React 18 + TypeScript
- First paint < 1.5s
### Progress
1. ✅ Component library upgrade
2. ❌ Router refactor (in progress)
...
```
### Create and Edit
```
You: Create a Lark doc called "Q2 Product Roadmap" with an outline
AI: Document created!
Link: https://xxx.larksuite.com/docx/xxx
Outline written: Goals, Timeline, Milestones, Resources
```
```
You: Replace all "TBD" with "Confirmed" in that doc
AI: Replaced 3 occurrences.
```
### Messaging — Send, Read, Search, Reply
```
You: What did the product team discuss today?
AI: Reading today's messages from "Product Team" group...
1. David (10:30): API v2 migration is done
2. Sarah (11:15): QA passed, ready for staging
3. Mike (14:22): Deployed to production
```
```
You: Send David a message: the API changes are deployed
AI: Message sent to David (as you).
```
```
You: Search for messages about "deployment" this week
AI: Found 5 messages across 3 chats:
- "Engineering" — David: "deployment pipeline updated" (Mon)
- "Product Team" — Sarah: "deployment checklist reviewed" (Tue)
...
```
```
You: Reply to Mike's message: great work, thanks!
AI: Reply sent in thread under Mike's message.
```
```
You: Share that doc to the product team group
AI: Document "Q2 Product Roadmap" shared to "Product Team" group.
```
> Messages support Markdown formatting, @mentions via ``, @all via ``, and emoji like `[SMILE]`.
### Calendar & Meetings
```
You: Schedule a sprint review tomorrow 2-3pm, invite David and Sarah
AI: Event created with Lark video meeting!
Link: https://meetings.feishu.cn/...
Invited: David, Sarah
```
```
You: What meetings do I have today?
AI: 3 events today:
1. 10:00-11:00 — Daily standup
2. 14:00-15:00 — Sprint review
3. 16:00-16:30 — 1:1 with Mike
```
### Bitable
```
You: Show me the records in this bitable https://xxx.feishu.cn/base/ABC123
AI: Found table "Task Tracker" with 15 records...
```
```
You: Add a new row: task="Fix login bug", status="In Progress", assignee="David"
AI: Record created.
```
### More Scenarios
```
You: Find David's open_id so I can @ him in the doc
You: Download the images from that document
You: Browse the "Product Docs" wiki and list sub-pages
You: Write the test results to a Lark doc and share it in the dev group
You: What did Sarah say yesterday in the engineering group?
```
---
CLI Direct Usage (advanced)
```bash
S=scripts/feishu_mcp.py
# Documents
python3 $S search-doc "weekly report" # Search
python3 $S fetch-doc ABC123def # Read
python3 $S list-docs # My Library
python3 $S create-doc "Meeting Notes" "## Topics\n\n- Item 1" # Create
python3 $S append ABC123def "## Update\n\nAppended content" # Append
python3 $S replace ABC123def "old text...end" "new text" # Replace
python3 $S insert-after ABC123def "some text" "inserted content" # Insert
python3 $S delete-range ABC123def "content to delete" # Delete
python3 $S get-comments ABC123def # Comments
python3 $S search-user "David" # Search user
python3 $S fetch-file filetoken123 # Get file
# Messaging
python3 $S list-groups # List groups
python3 $S send-msg oc_xxx "message" # Send to group
python3 $S send-msg ou_xxx "message" --user # DM user
python3 $S send-card oc_xxx '{"type":"template","data":{}}' # Send interactive card
python3 $S get-msgs oc_xxx today # Read today's messages
python3 $S get-msgs-user ou_xxx last_3_days # Read recent DMs
python3 $S search-msgs "deployment" # Search messages
python3 $S reply om_xxx "thanks!" # Reply to a message
python3 $S get-thread thread_xxx # Get thread replies
# Calendar
python3 $S list-events # Today's events
python3 $S create-event "Sprint Review" "2026-03-27T14:00" "2026-03-27T15:00" # All events include video meeting auto
python3 $S create-event "Demo" "2026-03-28T10:00" "2026-03-28T11:00" # All events include video meeting auto
# Bitable
python3 $S list-tables appToken # List tables in a bitable app
python3 $S list-records appToken tableId # List records
python3 $S create-record appToken tableId '{"Task":"Fix bug"}' # Create record
python3 $S update-record appToken tableId recordId '{"Status":"Done"}' # Update record
# Group Management
python3 $S create-group "Project Team" # Create group
python3 $S add-members oc_xxx '["ou_xxx1","ou_xxx2"]' # Add members
```
## How It Works
```
┌─► Lark Cloud Docs
AI Agent ──► feishu_mcp.py ──► ────┼─► Lark Messaging (MCP)
│ ├─► Calendar & Meetings (API)
├─ Official MCP ├─► Bitable Tables (API)
├─ + Open API └─► Group Management (API)
└─ Zero deps
```
Calls Lark's official Remote MCP service for documents and messaging, plus Open API for calendar, bitable, and group management. No local MCP server, no Node.js, no bot required — one Python script handles everything.
## FAQ
search-doc error "search:docs:read"
This permission requires UAT (user identity). Run `login` to authorize.
fetch-doc error "permission denied"
With TAT, the app needs document collaborator access. Use UAT (after `login`) to access all documents you have permission for.
Browser doesn't open after login
Check that you added the redirect URL `http://localhost:9876/callback` in your app's Security Settings.
Token expired
Tokens auto-refresh via refresh_token. If the refresh_token also expires (30 days), run `login` again.
## Security
- **Credentials** — App Secret is passed via environment variables, never exposed in conversations
- **Official Service** — All API calls go through Lark's official MCP service (`mcp.feishu.cn`)
- **Local Tokens** — OAuth tokens stored locally, never uploaded to external services
- **Third-party Content** — Document content comes from docs you have access to; be aware of potentially untrusted content
## Contributing
Issues and PRs welcome!
## License
MIT