Feishu Codex MCP v26.08.25

简体中文 | English

기업 자체 구축 앱을 통해 Feishu 지식 베이스와 권한이 부여된 공유 클라우드 드라이브를 Codex에 연결합니다. 이 MCP는 App ID와 App Secret으로 앱 자격 증명을 가져오며, 지식 베이스, 스프레드시트, 다차원 테이블, 문서 및 공유 파일을 나열·검색·읽기할 수 있고, 엄격한 경계 내에서 문서를 새로 만들거나 일부 범위를 수정할 수도 있습니다.

이 저장소는 GitHub에 공개 업로드할 수 있는 소스 코드 버전입니다. 실제 .env, 어떤 Feishu 콘텐츠, 로컬 백업, 다운로드 파일, 의존성 디렉터리 또는 배포 압축 패키지를 포함하지 않습니다.

기능과 보안 경계

• 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 설정 문서

1. Feishu 기업 자체 구축 앱 만들기

1. Feishu 오픈 플랫폼 개발자 콘솔을 열고 "기업 자체 구축 앱 만들기"를 선택합니다.

2. 앱 이름, 설명, 아이콘을 입력합니다.

3. "자격 증명 및 기본 정보"에서 App ID와 App Secret을 복사해 비밀번호 관리자에 임시 보관합니다.

4. App Secret을 채팅, Issue, 스크린샷, GitHub 등에 노출하지 마세요. 이미 유출되었다면 즉시 Feishu 콘솔에서 재설정해야 합니다.

이 프로젝트는 앱 자격 증명으로 tenant_access_token을 가져오므로 개인 OAuth 로그인이 필요하지 않습니다. 기업 관리자나 앱 관리자라는 지위가 앱에 모든 지식 베이스와 클라우드 드라이브 권한을 자동으로 부여하지는 않습니다. 리소스는 별도로 권한을 부여해야 합니다.

2. Feishu 권한 구성 및 배포

앱의 "권한 관리"에서 실제로 사용할 기능에 따라 권한을 신청합니다. Feishu 콘솔의 표시 이름은 조정될 수 있으므로 권한 코드로도 함께 검색하는 것을 권장합니다.

최소 권한 원칙: 읽기 도구만 사용한다면 쓰기 권한을 신청하지 마세요. Feishu 콘솔에 권한 이름이 위 표와 다르게 보인다면 해당 API 페이지에 게재된 최신 "필요한 권한"을 기준으로 삼으세요.

권한을 추가한 뒤에도 다음 절차가 필요합니다:

1. 앱 버전을 생성합니다.

2. 출시 신청을 제출합니다.

3. 담당 관리자가 새로운 권한 추가를 승인합니다.

4. 버전 상태가 "배포됨"인지 확인합니다.

콘솔에서 권한만 체크하고 게시하지 않으면 실제 실행 중인 앱에는 새 권한이 적용되지 않습니다.

3. 지식 베이스와 공유 클라우드 드라이브 권한 부여

API 권한은 앱의 능력이고, 리소스 권한은 특정 문서에 대한 접근 권한입니다. 둘 다 갖춰져야 합니다.

지식 베이스에 권한 부여

1. 연결하려는 지식 베이스 또는 대상 루트 노드를 엽니다.

2. 지식 공간의 멤버, 권한 설정 또는 문서 협업자 목록에 방금 만든 기업 자체 구축 앱을 추가합니다. Feishu 버전에 따라진입점이 "문서 앱 추가"로 표시될 수 있습니다.

3. 읽기만 사용할 경우 보기 권한을 부여하고, feishu_edit 또는 feishu_create가 필요할 때만 편집 권한을 부여합니다.

4. 앱이 검색되지 않으면 앱이 배포 승인되었는지, 사용 범위에 현재 계정이 포함되는지 먼저 확인합니다.

공유 클라우드 드라이브 폴더에 권한 부여

1. 대상 공유 폴더의 공유 또는 권한 설정 진입.

2. 해당 기업 자체 구축 앱을 추가하고 필요한 만큼 보기 또는 편집 권한을 부여합니다.

3. 명확한 루트 폴더 하나만 설정하고 기업 전체 클라우드 드라이브를 기본 경계로 두지 마세요.

관리자 자격으로도 지식 베이스와 폴더의 리소스 권한을 우회할 수 없습니다. 앱이 최종적으로 볼 수 있는 내용은 "배포 완료된 API 권한"과 "권한이 부여된 리소스"의 교집합입니다.

4. Wiki 토큰과 Drive 토큰 가져오기

Wiki token

대상 지식 베이스 노드 링크를 복사합니다. 예:

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

/wiki/ 뒤, 쿼리 매개변수 연나라 ? 앞부분이 곧 FEISHU_WIKI_ROOT_TOKEN입니다. 전체 링크를 FEISHU_WIKI_ROOT_URL에 먼저 넣으면 클릭 가능한 링크로 사용할 수 있습니다.

Drive token

권한이 부여된 공유 폴더 링크를 복사합니다. 예:

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

/folder/ 뒤, 쿼리 매개변수 앞부분이 FEISHU_DRIVE_ROOT_TOKEN입니다. 클라우드 드라이브 기능이 필요 없으면 비워 둡니다.

일반 문서 토큰, 지식 베이스 노드 토큰, 클라우드 드라이브 폴더 토큰을 섞어 사용하지 마세요. 링크 구조가 예시와 다르면 브라우저 주소창에서 리소스 유형을 확인하거나 Feishu API 디버깅 콘솔에서 토큰을 확인하세요.

5. 프로젝트 설치 및 .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

읽기 범위는 두 가지 옵션 중에 고를 수 있습니다:

• root: 기본값이며, 설정한 루트 노드와 그 하위 노드만 읽습니다. 공개 배포와 최소 권한 부여에 적합합니다.

• space: 루트 노드가 속한 지식 공간의 모든 노드를 읽습니다. 여러 디렉터리에 걸친 검색이 실제로 필요한 시나리오에 적합합니다.

space는 읽기 발견 범위만 확장하고 쓰기 경계는 확장하지 않습니다. .env는 .gitignore에 제외되어 있기 때문에 .env.example만 커밋할 수 있습니다.

사용 방법

Feishu 앱 구성을 완료한 다음, 아래 순서대로 연결합니다:

1. npm ci를 실행하여 잠금된 버전의 의존성을 설치합니다.

2. .env.example을 복사하여 .env로 만듭니다.

3. 자신의 App ID, App Secret, 지식 베이스 루트의 Wiki token을 입력합니다.

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_records 및 max_records로 반환량을 제한할 수 있습니다. 이 기능은 bitable:app:readonly 또는 동등한 상위 권한이 필요하며, 대상 다차원 테이블에 권한이 앱에 부여되어 있어야 합니다.

프로젝트 디렉터리에서 아래 명령을 실행하면 Feishu에 아무것도 쓰지 않는 온라인 읽기 전용 진단을 실행할 수 있습니다:

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

6. 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를 재시작해야 합니다. 재시작 후 Codex에 "Feishu 지식 베이스 루트 노드 보기"를 시켜서 연결을 확인할 수 있습니다.

7. 연결 확인 및 배포 패키지 생성

실제 Feishu 자격 증명으로 해 보는 실제 진단 명령:

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

읽기 전용 진단은 앱 인증, 지식 베이스 루트 노드, 현재 읽기 범위, 스프레드시트, 다차원 테이블, 공유 클라우드 드라이브를 확인하며 Feishu 내Content는 수정하지 않습니다.

의존성을 포함한 안전한 배포 패키지가 필요하면 다음을 실행합니다:

npm run package:safe

스크립트는 압축 패키지 화이트리스트를 검및 민감 값을 스캔하고 오프라인 부팅 점검을 수행한 뒤 프로젝트 상위 폴더에 飞书MCP-v26.08.25.zip을 생성합니다. 이 패키지는 배포 산출물이므로 GitHub에 커밋해서는 안 됩니다.

MCP 도구 목록

자주 묻는 질문

App ID, Secret이 있는데도 계속 내용을 읽지 못하는 이유

자격 증명은 앱 인증만 전담합니다. 앱 권한이 배포/승인되었는지, 대상 리소스가 앱에 권한 부여되었는지, token 런 호환되는지, 리소스가 설정된 읽기 범위에 들어 있는지 동시에 충족해야 합니다.

전부 브라우저 로그인이 필요 없는 이유

이 프로젝트는 기업 자체 구축 자기정을 통해 tenant_access_token을 얻으므로 앱 인증을 사용합니다. 브라우저 로그인은 보통 사용자 OAuth에 해당하는데, 이는 이를따른 또 다른 인증 방식이며 이 프로젝트에 필요하지 않습니다.

관리자인 전에 계정 권한을 설정해야 하는 이유

관리자는 당신의 계정 직함이고, API 요청은 기업 자체 구축 앱을 대표합니다. Feishu는 계정 관리 권한, 앱의 API 권한, 특정 리소스 권한을 분리합니다. 그래서 관리자가 앱을 만들었다고 해서 자동으로 기업 전체 리소스를 읽은 수 있는 구조가 아닙니다.

루트 노드는 보이는데 다른 지식 베이스 레이지가 보이지 않음

FEISHU_WIKI_READ_SCOPE를 확인하세요. root는 루트 노드의 하위 페이지들만 탐색합니다. 동일 지식 공간의 다른 디렉터리를 읽어야 한다면 space로 변경한 뒤 Codex를 재시작하세요. 그래도 안 보인다면 지식 공간에서 앱에 대한 리소스 권한이 있는지 확인하세요.

다차원 테이블을 읽을 수 없는 경우

앱이 최소 bitable:app:readonly 이상의 동등 권한을 가지고 있는지, 그 권한 버전이 배포되었는지, 대상 다차원 테이블에서 앱을 문서 협업자로 추가했는지 확인하세요.

Codex에서 저장소에 Feishu 도구가 맞

~/.codex/config.toml의 경로가 merge 존재하는지, 프로젝트에서 npm ci를 수행했는지 .env가 cwd에 올바른 위치에 있는지 확인하고 Codex를 완전히 종료 후 재시작하세요. 미리 node src/server.js로 실행 오류도 점검해볼 수 있습니다. 정상적으로 시작된 stdio MCP 서버는 입력을 기다리며 웹페이지 로그인 창을 띄워서 표시되지 않습니다.

보안 설명과 업로드 검사

공개 저장소와 안전한 배포 패키지에는 실제 .env, App ID, App Secret, Wiki/Drive token, 기업 지식 베이스 URL, 다운로드 파일 또는 로컬 백업이 포함되어서는 안 됩니다. 안전 패키지 생성기는 압축 패키지 화이트리스트를 검사하고 로컬 .env의 민감 값을 스캔하며 실제 구성이 발견되면 배포를 거부합니다.

FEISHU_WIKI_READ_SCOPE=space는 동일 지식 공간의 읽기만 범위를 확장합니다. 새로 만들기, 편집, 백업으로 복원 등은 여전히 설정된 루트 노드 범위 안이며, 다차원 테이블 기능은 records를 만들 수 있는 쓰기 도구를 제공하지 않고 읽기 전용입니다.

인증 정보가 유출된 의심이 되면:

1. 즉시 Feishu 오픈 플랫폼에서 App Secret을 재설정합니다.

2. 앱 권한을 회수하거나 축소하고, 지식 베이스·다차원 테이블·공유 클라우드 드라이브에 대한 리소스 권한을 재점검합니다.

3. 이전 자격 증명이 저장된 로컬 파일과 압축 패키지를 삭제합니다.

4. Git 기록에 자격 증명이 들어갔다면 기록을 정리한 뒤에 업로드하세요. 이후 항상 새로운 데이터 자격 증명을 기준으로 합니다.

업로드 전에 하나씩 점검하세요:

• 저장소에는 .env.example만 있고 .env 또는 다른 실제 자격 증명 파일이 없다.

• App Secret, 실제 Wiki/Drive token, 기업 도메인 또는 Feishu 데이터가 추적되는 어떤 파일에도 없다.

• node_modules, data, downloads, backups, 로그 또는 압축 파일이 없다.

• git status --short가 예상된 변경 사항만 표시하거나 지돼 있다.

• git ls-files로 업로드될 전체 파일 목록을 다시 검토 했다.

• 자격 증명이 Git 역사에 들어간 적이 있다면 현재 파일만 삭제는 불완전하다. Feishu Secret을 재설정한 뒤 기록을 정리해야 한다.

아래 명령어로 빠르게 확인할 수 있습니다:

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

마지막 명령은 README의 자리 표시자 샘플을 찾아낼 수 있습니다; 자리 표시자일 뿐이며 실제 값이 아니라 검토필요하세요.