Feishu Codex MCP v26.08.25

简体中文 | English

Connect Feishu knowledge bases and authorized shared cloud drives to Codex through an enterprise self-built app. This MCP uses the App ID and App Secret to obtain an app identity, and can list, search, and read wiki bases, spreadsheets, bitables, and shared files. It can also create new documents or make small in-place edits within strict boundaries.

This repository is the source version that can be publicly uploaded to GitHub. It does not contain a real .env, any Feishu content, local backups, downloaded files, dependency directories, or release archives.

Features and Security Boundaries

• Uses the Feishu app identity; you don't need to log in to a personal Feishu account in the browser.

• The App ID and App Secret only prove "which app this is"; the API permissions and target resource authorization together determine "what it can access".

• By default, FEISHU_WIKI_READ_SCOPE=root; it only reads the specified root node and its descendants.

• You can change the read scope to space to read all nodes in the wiki space containing the root node; write operations are still limited to the configured root node or shared folder.

• A local backup is saved before modifying a document; restore operations create a new draft and never directly overwrite the current document.

• No destructive tools are provided, such as delete, move, share, or permission modification.

• Codex uses the writes approval mode for write tools, and still asks for confirmation before executing.

Related MCP server: Feishu MCP Server

Prerequisites

You need:

• A Feishu enterprise account with permission to create, publish, or approve an enterprise self-built app;

• Windows 10/11;

• Node.js 24 or higher;

• Codex Desktop, Codex CLI, or the Codex IDE extension;

• A wiki node that you plan to authorize to the app; a shared cloud drive folder is optional.

Official resources:

• Feishu Open Platform Developer Backend

• Feishu Open Platform Development Documentation

• Codex MCP configuration documentation

1. Create a Feishu Enterprise Self-built App

1. Open the Feishu Open Platform Developer Backend and select "Create Enterprise Self-built App".

2. Fill in the app name, description, and icon.

3. Go to "Credentials and Basic Information", copy the App ID and App Secret, and temporarily store them in a password manager.

4. Do not send the App Secret to chat, Issues, screenshots, or GitHub. If it has already leaked, reset it immediately in the Feishu backend.

This project uses the app identity to obtain a tenant_access_token, so no personal OAuth login is required. Being an enterprise admin or an app admin does not mean the app automatically has all wiki and drive permissions; resources still need to be authorized separately.

2. Configure and Publish Feishu Permissions

Go to the app's "Permission Management" and apply for the permissions you actually need. The Chinese names shown in the Feishu backend may change, so we recommend also searching by permission code.

Principle of least privilege: if you only use read tools, do not apply for writable permissions. If the permission name shown in the Feishu backend differs from the table above, follow the latest "required permission" listed on the corresponding API page.

After adding permissions, you must also:

1. Create an app version;

2. Submit it for publishing;

3. Have the enterprise admin approve the newly added permissions;

4. Confirm the version is published.

Only checking permission boxes without publishing will not give the running app identity the new permissions.

3. Authorize the Knowledge Base and Shared Drive

API permissions are about app capabilities; resource authorization is about access to specific documents, and both are required.

Authorize the knowledge base

1. Open the knowledge base or target root node you plan to connect.

2. Add the newly created enterprise self-built app to the knowledge space members, permission settings, or document collaborators. Different Feishu versions may show the entry as "Add app to document".

3. Grant read-only permission when the app only needs to read; grant edit permission only when feishu_edit or feishu_create is needed.

4. If you can't find the app, first confirm that the app is published and approved, and that its available scope includes the current account.

Authorize a shared drive folder

1. Open the sharing or permission settings of the target shared folder.

2. Add this enterprise self-built app and grant view or edit permission as needed.

3. Only configure one explicit root folder; do not use the entire enterprise drive as the default boundary.

An admin role will not bypass the resource authorization for knowledge bases and folders. What the app can ultimately see is the intersection of "published API permissions" and "authorized resources".

4. Obtain the Wiki and Drive tokens

Wiki token

Copy the target wiki node link, for example:

https://your-tenant.feishu.cn/wiki/WIKI_NODE_TOKEN?from=copylink

The part after /wiki/ and before the query parameter ? is the FEISHU_WIKI_ROOT_TOKEN. If you fill in FEISHU_WIKI_ROOT_URL with the full link, it will be used to generate clickable links.

Drive token

Copy an authorized shared folder link, for example:

https://your-tenant.feishu.cn/drive/folder/DRIVE_FOLDER_TOKEN

The part after /folder/ and before the query parameter is the FEISHU_DRIVE_ROOT_TOKEN. Leave it empty if you do not need drive access.

Do not mix ordinary document tokens, wiki node tokens, and drive folder tokens. If the link structure differs from the example, first confirm the resource type in the browser address bar, or check the token through the Feishu API debug console.

5. Install the Project and Fill in .env

In PowerShell, go to the project directory:

npm ci
Copy-Item .env.example .env
notepad .env

Fill in your own values in .env:

FEISHU_APP_ID=<你的 App ID>
FEISHU_APP_SECRET=<你的 App Secret>
FEISHU_WIKI_ROOT_TOKEN=<知识库根节点 Wiki token>
FEISHU_WIKI_ROOT_URL=https://your-tenant.feishu.cn/wiki/<知识库根节点 Wiki token>
FEISHU_WIKI_READ_SCOPE=root
FEISHU_DRIVE_ROOT_TOKEN=<共享文件夹 Drive token；不用云盘时留空>
FEISHU_API_BASE_URL=https://open.feishu.cn/open-apis
FEISHU_BACKUP_DIR=data/backups

The read scope has two options:

• read: the default, only reads the configured root node and its children, suitable for public deployment and least privilege.

• space: reads all nodes in the wiki space to which the root node belongs, suitable for scenarios that truly need cross-directory search.

space only expands the read discovery scope, not the write boundary. .env is already excluded by .gitignore; you can only commit .env.example.

Usage Instructions

After completing the Feishu app configuration, connect in the following order:

1. Run npm ci to install the pinned dependencies.

2. Copy .env.example to .env.

3. Fill in your own App ID, App Secret, and Wiki token for the knowledge base root node.

4. Keep FEISHU_WIKI_READ_SCOPE=root to limit reads to the root node and its descendants; only switch to space when you really want to read other directories in the same knowledge space.

5. Fill in FEISHU_DRIVE_ROOT_TOKEN when you need to read the shared drive; leave it empty if not.

6. Double-click connect-feishu.cmd, fully exit and restart Codex after you see Setup completed.

7. Tell Codex to run "list the Feishu wiki root directory" to confirm the MCP is connected.

8. After changing the app, directory, or read scope, edit .env and restart Codex again.

Even if the knowledge base root node has no child pages, feishu_list_wiki still returns the root node itself. space mode lets listing, search, and reading cover the entire wiki space, but create, edit, and restore draft operations are still limited to the original FEISHU_WIKI_ROOT_TOKEN.

When reading a bitable in a wiki base, feishu_read can use the table parameter to specify the table, and max_tables / max_records to limit the returned volume. This requires bitable:app:readonly or an equivalent higher permission, and the target bitable must be authorized to the app.

Run the following command in the project directory to perform a read-only online diagnostic that does not write any Feishu content:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts/test-live.ps1

6. Connect to Codex

Automatic configuration (Windows)

After installing dependencies and filling in .env, double-click:

connect-feishu.cmd

The script keeps the other settings in ~/.codex/config.toml and only updates the [mcp_servers.feishu] section. After it succeeds, fully quit and reopen Codex.

Manual configuration

Codex's MCP configuration file is located at ~/.codex/config.toml. Change the path to the absolute path on your machine; use / for Windows paths:

[mcp_servers.feishu]
command = "C:/Program Files/nodejs/node.exe"
args = ["C:/path/to/FeishuCodexMCP/src/server.js"]
cwd = "C:/path/to/FeishuCodexMCP"
startup_timeout_sec = 20
tool_timeout_sec = 120
default_tools_approval_mode = "writes"

There is no need to write the App ID or Secret into config.toml. The server reads the configuration from the .env in the directory pointed to by cwd. Codex Desktop, CLI, and IDE extensions share this same configuration on the same machine.

You must restart Codex after modifying the configuration. After restarting, you can tell Codex to run list the Feishu wiki root directory to confirm the connection.

7. Check the Connection and Create a Release Package

Run the read-only diagnostic that requires real Feishu credentials:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts/test-live.ps1

The read-only diagnostic checks app authentication, the root node, the current read scope, spreadsheets, bitables, and the authorized shared drive, without modifying any Feishu content.

When you need to build a release package bundled with dependencies, run:

npm run package:safe

The script verifies the archive whitelist, scans for sensitive values, and performs an offline startup check, then generates 飞书MCP-v26.08.25.zip in the project's parent directory. That archive is a release artifact and should not be committed to GitHub.

MCP Tool List

FAQ

I have App ID and App Secret, but still can't read content?

Credentials are only responsible for the app identity authentication. You also need the following at the same time: the app permission has been published and approved, the target resources are authorized for the app, the token type is correct, and the resource is in the configured read scope.

Why is browser login not required?

This project uses an enterprise self-built app identity and obtains the tenant_access_token and through App ID and Secret. Browser login is usually user OAuth, which is another authentication method and is not a required step for this project.

Why do I still need to configure permissions if I'm an admin?

Admin is the role of your account; API requests represent the enterprise self-built app. Feishu separates the account management, app API permissions, and specific resource permissions, so an app created by an admin does not automatically read all company data.

I can read the root node, but not other wiki pages

Check FEISHU_WIKI_READ_SCOPE. A value of root only traverses the descendants of the root node; if you really need to read other directories in the same wiki space, change it to space and restart Codex. If it is still not visible, check the authorization of the space to the app.

Bitable cannot be read

Confirm that the app has at least bitable:app:readonly or an equivalent higher permission, plus the permission version has been published, and that the bitable has been authorized to the app.

No Feishu tools appear in Codex

Check that the path in ~/.codex/config.toml exists, that npm ci has been run in the project, and that .env is in cwd; then fully exit and restart Codex. You can also run node src/server.js to check for startup errors; a normal std MCP server waits for input, not a error page.

Security Notes and Upload Checks

Neither the public repo nor the release package may include a real .env, App ID, App Secret, Wiki/Drive token, enterprise knowledge base URLs, downloaded files, or local backups. The secure packager verifies the archive whitelist and scans local .env for sensitive values; it refuses to publish if it finds real configuration.

FEISHU_WIKI_READ_SCOPE with space only expands the read scope in the same wiki space. Create, edit, and restore operations remain scoped to the configured root node; bitable features remain read-only, and no tool for write is provided.

If you suspect credential leakage:

1. Immediately reset the App Secret in the Feishu Open Platform backend.

2. Recognize or narrow the app permissions, and review the resource authorizations for wiki base, bitables, and shared drive.

3. Delete local files and archives that contain the old credentials.

4. If credentials have entered Git history, clean up the history before re-uploading, and ensure the new Secret is always used.

Confirm the following list before uploading:

• The repo contains only .env.example, and no .env or other real credential files.

• The App Secret, real Wiki/Drive tokens, enterprise domain, and Feishu content do not appear in any tracked file.

• No node_modules, data, downloads, backups, logs, or archives.

• git status --short also only shows or dedented archives.

• Use git ls-files to review the full file list that will be uploaded.

• If credentials were previously in Git history, simply removing the current file still got archived with old credentials; you should reset the Feishu Secret and clean up the history.

Use some commands because they may identify the .env placeholder, for an extra primary:

git ls-files
git grep -n -I -E "FEISHU_APP_SECRET=.+|tenant_access_token|your-tenant\.feishu\.cn"

The last command can hit the placeholder examples in the README; manually confirm they are just placeholders, not real values.