Feishu Codex MCP v26.08.25

简体中文 | English

企業内製アプリを通じて、Feishu のナレッジベースと権限付与済みの共有クラウドドライブを Codex に接続します。この MCP は App ID と App Secret を使用してアプリの身元を取得し、ナレッジベース、スプレッドシート、多次元テーブル、共有ファイルの一覧・検索・読み取りができます。また、厳密な境界内で新規作成や一部変更もできます。

本リポジトリは、GitHub へ公開できるソースコード版です。実際の .env、Feishu コンテンツ、ローカルバックアップ、ダウンロードファイル、依存ディレクトリ、リリース用 ZIP は含まれません。

機能と安全境界

• Feishu アプリの身元を使用するため、ブラウザーでの個人 Feishu アカウントへのログインは不要です。

• App ID と App Secret は「どのアプリか」を示すだけです。API 権限と対象リソースの権限付与が、その組み合わせで「何にアクセスできるか」を決定します。

• デフォルトは FEISHU_WIKI_READ_SCOPE=root で、指定したルートノードとその子孫のみを読み取ります。

• 読み取り範囲を space に変更すると、ルートノードが属するナレッジスペース内の全ノードを読み取れます。書き込み操作は引き続き、設定したルートノードまたは共有フォルダー内に限定されます。

• ドキュメントを変更する前にはローカルバックアップを保存します。復元操作では新しい下書きを作成し、現在のドキュメントを直接上書きしません。

• 削除、移動、共有、権限変更などの破壊的なツールは提供しません。

• Codex は書き込みツールに writes 承認モードを使用し、実行前にも確認を求めます。

Related MCP server: Feishu MCP Server

準備

必要なもの：

• 企業内製アプリを作成・リリース・承認できる権限を持つ Feishu 企業アカウント。

• Windows 10/11。

• Node.js 24 以降。

• Codex Desktop、Codex CLI、または Codex IDE 拡張機能。

• アプリに権限付与する予定のナレッジベースルートノード。共有クラウドドライブフォルダーは任意です。

公式サイト：

• 飛書开放平台开发者后台 - Feishu 開発者バックエンド

• 飛書开放平台开发文档 - Feishu 開発ドキュメント

• Codex MCP 設定ドキュメント

一、Feishu アプリを作成する

1. Feishu 開発者バックエンドを開き、「企業内製アプリを作成」を選択します。

2. アプリ名、説明、アイコンを入力します。

3. 「認証情報と基本情報」に移動し、App ID と App Secret をコピーして、パスワードマネージャーに一時的に保存します。

4. App Secret をチャット、Issue、スクリーンショット、GitHub に送らないでください。漏洩した場合は、ただちに Feishu バックエンドでリセットしてください。

このプロジェクトはアプリの身元を使用して tenant_access_token を取得するため、個人の OAuth ログインは必要ありません。企業管理者やアプリ管理者であっても、アプリが自動的にすべてのナレッジベースやクラウドドライブへの権限を持つわけではありません。リソースには個別の権限付与が必要です。

二、Feishu 権限の設定と公開

アプリの「権限管理」を開き、実際に使用する機能に応じた権限を申請します。Feishu バックエンド上の中国語名が変更される場合があるため、権限コードでも検索することをお勧めします。

最小権限の原則：読み取り専用ツールのみ使用する場合は、書き込み権限を申請しないでください。Feishu バックエンドで表示される権限名が上記の表と異なる場合は、対応する API ページに記載されている最新の「必要権限」を確認してください。

権限を追加した後、以下も実施します：

1. アプリのバージョンを作成する。

2. 公開を申請する。

3. 企業管理者が新しい権限を承認する。

4. バージョン状態が「公開済み」であることを確認する。

バックエンドで権限をチェックしただけでは、公開していないと、実行中のアプリに新しい権限は反映されません。

三、ナレッジベースと共有クラウドドライブの権限付与

API 権限はアプリの機能、リソース権限はドキュメントへのアクセス権です。どちらも必要です。

ナレッジベースの権限付与

1. 接続するナレッジベースまたは対象ルートノードを開きます。

2. ナレッジスペースのメンバー、権限設定、またはドキュメント共有者に、作成したての企業アプリを追加します。Feishu のバージョンによっては「ドキュメントアプリを追加」と表示される場合があります。

3. 読み取りのみの場合は閲覧権限を付与し、feishu_edit や feishu_create が必要な場合にのみ編集権限を付与します。

4. アプリが見つからない場合は、公開され、承認され、利用可能な範囲に現在のアカウントが含まれていることを確認します。

共有ドライムフォルダーの権利付与

1. 対象の共有フォルダーの「共有」または「権限」設定を開きます。

2. 企業アプリを追加し、閲覧・編集権限を必要に応じて付与します。

3. 明確なルートフォルダーのみを設定し、企業全体のクラウドドライブをデフォルトにしないでください。

管理者の身分であっても、ナレッジベースやフォルダーのリソース権限を無視することはできません。アプリが最終的に表示できるのは、「公開済みの API 権限」と「権限付与済みのリソース」の共通部分です。

四、Wiki と Drive トークンを取得する

Wiki トークン

対象のナレッジベースノードリンクをコピーします。例：

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

/wiki/ の後で、クエリパラメータ ? の前の部分が FEISHU_WIKI_ROOT_TOKEN です。完全なリンクは FEISHU_WIKI_ROOT_URL に入力でき、クリック可能なリンクの生成に使用します。

Drive トークン

権限付与済みの共有フォルダーのリンクをコピーします。例：

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

/folder/ の後で、クエリパラメータの前の部分が FEISHU_DRIVE_ROOT_TOKEN です。クラウドドライブ機能が不要な場合は空で可です。

通常のドキュメント、ナレッジベースノードのトークン、クラウドドライブのフォルダートークンを混同しないでください。リンク構造が例と異なる場合は、まずブラウザーのアドレスバーでリソースタイプを確認し、Feishu API デバッグコンソールでトークンを照合します。

五、プロジェクトのインストールと .env の設定

PowerShell でプロジェクトディレクトリに入ります：

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

.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

読み取り範囲には 2 つの選択肢があります：

• root：デフォルト値。設定したルートノードとその子ノードのみ読み取り。公開デプロイと最小権限に適しています。

• space：そのルートノードが属するナレッジスペースの全ノードを読み取りたいとき。ディレクトリをまたいだ検索が必要な場合に適しています。

space は読み取りの発見範囲を広げるだけで、書き込みの境界は変えません。.env は .gitignore で除外されています。コミットできるのは .env.example だけです。

利用手順

Feishu アプリの設定が完了したら、次の順で接続します：

1. npm ci を実行し、ロックされたバージョンの依存関係をインストールします。

2. .env.example をコピーして .env にします。

3. 自分の App ID、App Secret、ナレッジベースのルートノード Wiki トークンを設定します。

4. FEISHU_WIKI_READ_SCOPE=root のままにすると、読み取りをルートノードとその子孫に制限できます。別のディレクトリを読み取る必要がある場合のみ space に変更します。

5. 共有クラウドドライブを読む場合は FEISHU_DRIVE_ROOT_TOKEN を設定します。不要な場合は空にします。

6. connect-feishu.cmd をダブルクリックし、Setup completed と表示されたら、完全に終了して Codex を再起動します。

7. Codex に「Feishu のナレッジベース・ルートをすべて表示」を実行させ、MCP が接続されていることを確認します。

8. アプリ、フォルダー、読み取り範囲を変更した場合は .env を編集して、再び Codex を再起動します。

ナレッジベースのルートに子ページがなくても feishu_list_wiki はルートノード自体を返します。space モードでは同一ナレスペース内への表示・検索・読み取りが可能ですが、作成・編集・下書きの復元は元の FEISHU_WIKI_ROOT_TOKEN の範囲に制限されます。

ナレッジベース内の多次元テーブルを読み取る場合、feishu_read で table によってデータテーブルを指定し、max_tables や max_records で返す量を制限できます。この機能には bitable:app:readonly または同等以上の権限が必要で、対象の多次元テーブルにもアプリへの権限付与が必要です。

プロジェクトディレクトリで次のコマンドを実行すると、Feishu の内容を変更しないオンラインの読み取り専用診断ができます：

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

六、Codex に接続するには

自動設定（Windows）

依存関係をインストールし、.env を設定したら、次のファイルをダブルクリックします：

connect-feishu.cmd

スクリプトは ~/.codex/config.toml 内の他設定を保持し、[mcp_servers.feishu] 階のみを更新します。成功後、完全に終了して罅 Codex を開きます。

手動設定

Codex の MCP 設定ファイルは ~/.codex/config.toml にあります。パスは自分のマシンの絶対パスに変更してください。Windows パスはスラッシュ / を使うことをお勧めします：

[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"

ここに App ID や Secret を config.toml に書き込む必要はありません。サーバーは cwd の指すディレクトリの .env から設定を読み取ります。Codex Desktop、CLI、IDE 拡張機能は同じマシンで同じ設定を共有します。

設定変更後は必ず Codex を再起動してください。再起動後、「Feishu のナレッジベースを一覧」を実行させて接続を確認できます。

七、接続確認とリリースパッケージの作成

実際の Feishu と Socket を必要とする読み取り専用診断を実行します：

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

読み取り専用診断は、アプリの認証、ナレッジベースのルートノード、現在の読み取り範囲、スプレッドシート、多次元テーブル、共有クラウドドライブを確認しますが、Feishu の内容は変更しません。

依存を含むリリースパッケージの生成が必要な場合は次を実行します：

npm run package:safe

スクリプトは ZIP のホワイトリストの照合、敏感な値のスキャン、オフライン起動チェックを行い、プロジェクトの 1 つ上のフォルダーに 飞书MCP-v26.08.25.zip を生成します。この ZIP はリリース物であり、GitHub にはコミットしないでください。

MCP ツール一覧

よくある質問

App ID と Secret がありながら、内容を取得できないのはなぜですか？

認証情報はアプリ本人の確認資料にすぎません。次の条件をすべて満たす必要があります：アプリの権限が公開・承認済み、対象リソースがアプリに紐付されている、トークンの型が正しい、リソースが設定した読み取り範囲内にある。

なぜブラウジングのログインが不要なのですか？

本プロジェクトでは企業アプリの身元を使用し、App ID と App Secret から tenant_access_token を取得するためです。ブラウザーのログインは通常、ユーザー OAuth を対象にしたもので、本人の必須手順ではありません。

管理者なのに、まだ権限設定が必要なのは？

管理者はあなたのアカウント上の役割です。API の要求は企業アプリを代表します。Feishu では、アカウント管理権限、アプリ、API エリアの権限と、個別リソースの権限が分離しているため、アプリを作成した管理者の権限だけでは全社のドキュメントを自動的に読めないのです。

ルートノードは読めるが、他のナレッジベースのページが見えない

FEISHU_WIKI_READ_SCOPE=root の場合は、ルートの直下だけが Walk されます。同じナレッジの他のディレクトリを読む必要が出たら場合は、space に変更し Codex を再起動してください。それでも見えない場合は、ナレッジスペースのアプリへの権限付与を確認します。

多次元テーブルが読み取れない

アプリに少なくとも bitable:app:readonly または同等以上の権限があり、権限のバージョンが公開され、その多次元テーブルにアプリが協力者として追加されていることを確認してください。

Codex に Feishu ツールが表示されない

~/.codex/config.toml の存在、プロジェクトディレクトリでの npm ci の実行、.env の配置（cwd）を確認し、完全に終了して Codex を再起動してください。また、node src/server.js を実行して起動エラーを確認できます。正常な stdio MCP サーバーは起動後入力をリーし、Teapot のログインページを開きません。

安全上の注意とアップロード前チェック

公開リポジトリ とリリースパッケージには、実際の .env、App ID、App Secret、Wiki/Drive トークン、企業ドメイン、ダウンロードファイルやローカルバックアップを含めてはなりません。安全パッケージツールは ZIP のホワイトリストをうち、ローカルの .env 内の敏感値を走査し、実均が実 gedetect 場合は公開が拒否されます。

FEISHU_WIKI_READ_SCOPE=space では、同一ナレッジスペース内の読み取り範囲のみが広がります。作成・編集・ドラフトの復元は設定したルートノードに限定されます。多次元テーブル機能は読み取りのみのため、レコード書き込みツールは提供しません。

認証情報の漏えいが疑われるとき：

1. ただちに Feishu オープンプラットフォームで App Sccccr を再不使用してください。

2. アプリの権限を撤回・縮小し、ナレッジベース・多次元テーブル・共有クラウドドライブの権限を確認します。

3. 旧認証情報の含まれたローカルファイルと ZIP を削除します。

4. 認証情報が Git リポジトリに存在した場合は、そのまま削除だけではなく、Feishu Sidecret をリセットしてから履歴を整理・再コミットしてください。

公開前に:

• リポジトリに .env.example のみがあり、.env やその他認証情報のファイルが存在しない。

• App Secret 、実際の Wiki/Drive トークン、企業ドメイン、Feishu のドキュメントがトラッキングファイルに入っていない。

• node_modules、data、downloads、backups、ログ、ZIP がない。

• git status --short は予期した変更のみか空である。

• git ls-files でアップされる全ファイルを確認した。

• 認証情報についても、Git 過去にあった場合は、現在の削除だけではなく、Feishu Secret をリセットした上で「history」のクリーンアップを。

なお、上記のチェックには次のコマンドで簡単に実行できます：

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

最後のコマンドは README 内のパースホルダー例に誤って一致することがあります。それらがただのプレースホルダーであることを手動で確認してください。