페이슈/라크 OpenAPI MCP

영어 | 중문

개발자 문서 검색 MCP | 공식 문서

⚠️ 베타 버전 안내 : 이 도구는 현재 베타 단계입니다. 기능 및 API가 변경될 수 있으니, 버전 출시에 대한 최신 정보를 확인해 주세요.

이는 사용자가 Feishu/Lark 플랫폼에 빠르게 연결하고 AI 에이전트와 Feishu/Lark 간의 효율적인 협업을 지원할 수 있도록 설계된 Feishu/Lark 공식 OpenAPI MCP(Model Context Protocol) 도구입니다. 이 도구는 Feishu/Lark Open Platform API 인터페이스를 MCP 도구로 캡슐화하여 AI 비서가 이러한 인터페이스를 직접 호출하고 문서 처리, 대화 관리, 일정 예약 등 다양한 자동화 시나리오를 구현할 수 있도록 지원합니다.

특징

• 완전한 Feishu/Lark API 툴킷: 메시지 관리, 그룹 관리, 문서 작업, 캘린더 이벤트, Bitable 및 기타 핵심 기능 영역을 포함한 거의 모든 Feishu/Lark API 인터페이스를 캡슐화합니다.

• 이중 인증 지원:

  • 앱 액세스 토큰 인증을 지원합니다

  • 사용자 액세스 토큰 인증을 지원합니다

• 유연한 통신 프로토콜:

  • Trae/Cursor/Claude와 같은 AI 도구와의 통합에 적합한 표준 입출력 스트림(stdio) 모드를 지원합니다.

  • HTTP 기반 인터페이스를 제공하는 SSE(Server-Sent Events) 모드를 지원합니다.

• 다양한 사용 시나리오에 맞춰 여러 구성 방법을 지원합니다.

도구 목록

지원되는 모든 Feishu/Lark 도구의 전체 목록은 tools.md 에서 확인할 수 있으며, 여기서 도구는 설명과 함께 프로젝트 및 버전별로 분류됩니다.

준비

Feishu/Lark 애플리케이션 만들기

lark-mcp 도구를 사용하기 전에 Feishu/Lark 애플리케이션을 만들어야 합니다.

1. Feishu Open Platform 또는 Lark Open Platform을 방문하여 로그인하세요.

2. "콘솔"을 클릭하고 새 애플리케이션을 만듭니다.

3. API 인증에 사용될 앱 ID와 앱 비밀번호를 얻으세요.

4. 사용 시나리오에 따라 애플리케이션에 필요한 권한을 추가하세요.

5. 사용자로서 API를 호출해야 하는 경우 OAuth 2.0 리디렉션 URL을 설정하고 사용자 액세스 토큰을 얻으세요.

자세한 애플리케이션 생성 및 구성 지침은 Feishu 오픈 플랫폼 문서 - 애플리케이션 생성 또는 Lark 오픈 플랫폼 문서를 참조하세요.

Node.js 설치

lark-mcp 도구를 사용하기 전에 Node.js 환경을 설치해야 합니다.

macOS에 Node.js 설치

1. Homebrew 사용(권장) :

   지엑스피1

2. 공식 설치 프로그램 사용 :

   • Node.js 웹사이트를 방문하세요

   • LTS 버전을 다운로드하고 설치하세요

   • 설치 후 터미널에서 확인하세요.

     node -v npm -v

Windows에 Node.js 설치

1. 공식 설치 프로그램 사용 :

   • Node.js 웹사이트를 방문하세요

   • Windows 설치 프로그램(.msi 파일)을 다운로드하여 실행하세요.

   • 설치 마법사를 따라 설치를 완료하세요.

   • 설치 후 명령 프롬프트에서 확인하세요.

     node -v npm -v

2. nvm-windows 사용하기 :

   • nvm-windows 다운로드

   • nvm-windows 설치

   • nvm을 사용하여 Node.js를 설치하세요.

     nvm install latest nvm use <version_number>

설치

lark-mcp 도구를 전역적으로 설치합니다.

사용 가이드

Trae/Cursor/Claude와 함께 사용

Trae, Cursor 또는 Claude와 같은 AI 도구에 Feishu/Lark 기능을 통합하려면 구성 파일에 다음을 추가하세요.

사용자 ID로 API에 액세스하려면 사용자 액세스 토큰을 추가할 수 있습니다.

사용자 정의 API 구성

기본적으로 MCP 서비스는 공통 API를 활성화합니다. 다른 도구나 특정 API 또는 프리셋만 활성화하려면 -t 매개변수(쉼표로 구분)를 사용하여 지정할 수 있습니다.

사전 설정 도구 컬렉션에 대한 자세한 정보

다음 표에서는 각 API 도구와 다양한 사전 설정 컬렉션에 포함된 내용을 자세히 설명하여 필요에 맞는 적절한 사전 설정을 선택하는 데 도움을 줍니다.

참고 : 표에서 "✓" 표시는 해당 도구가 해당 사전 설정에 포함되어 있음을 나타냅니다. -t preset.xxx 명령을 사용하면 해당 열에 "✓" 표시가 있는 도구만 활성화됩니다.

고급 구성

명령줄 매개변수

lark-mcp mcp 도구는 유연한 MCP 서비스 구성을 위한 다양한 명령줄 매개변수를 제공합니다.

매개변수 사용 예

1. 기본 사용법 (애플리케이션 ID 사용):

   lark-mcp mcp -a cli_xxxx -s yyyyy

2. 사용자 ID 사용 :

   lark-mcp mcp -a cli_xxxx -s yyyyy -u u-zzzz

   참고 : 사용자 액세스 토큰은 Feishu Open Platform의 인증 절차 또는 Lark Open Platform의 인증 절차를 통해 획득하거나, API 디버깅 콘솔을 사용하여 획득할 수 있습니다. 사용자 액세스 토큰을 사용하면 해당 사용자의 ID로 API 호출이 수행됩니다.

3. 특정 토큰 모드 설정 :

   lark-mcp mcp -a cli_xxxx -s yyyyy --token-mode user_access_token

   참고 : 이 옵션을 사용하면 API를 호출할 때 사용할 토큰 유형을 명시적으로 지정할 수 있습니다. auto 모드(기본값)는 API를 호출할 때 LLM에 의해 결정됩니다.

4. Lark 또는 KA 도메인 지정 :

   # Lark international version lark-mcp mcp -a <your_app_id> -s <your_app_secret> -d https://open.larksuite.com # Custom domain (KA domain) lark-mcp mcp -a <your_app_id> -s <your_app_secret> -d https://open.your-ka-domain.com

5. 특정 API 도구 또는 다른 API 도구만 활성화 :

   lark-mcp mcp -a cli_xxxx -s yyyyy -t im.v1.chat.create,im.v1.message.create

   참고 : -t 매개변수는 다음과 같은 사전 설정 도구 컬렉션을 지원합니다.

   • preset.default - 모든 사전 설정 도구가 포함된 기본 도구 세트

   • preset.im.default - 그룹 관리, 메시지 전송 등 인스턴트 메시징 관련 도구

   • preset.bitable.default - 테이블 생성, 레코드 관리 등 Bitable 관련 도구

   • preset.bitable.batch - 일괄 생성 및 레코드 업데이트 기능을 포함한 Bitable 일괄 작업 도구

   • preset.doc.default - 문서 내용 읽기, 권한 관리 등 문서 관련 도구

   • preset.task.default - 작업 생성, 멤버 관리 등 작업 관리 관련 도구

   • preset.calendar.default - 캘린더 이벤트 생성, 여유/바쁨 상태 조회 등의 캘린더 이벤트 관리 도구입니다.

6. 특정 포트 및 호스트를 사용하여 SSE 모드 사용 :

   lark-mcp mcp -a cli_xxxx -s yyyyy -m sse --host 0.0.0.0 -p 3000

7. 설정 도구 언어를 중국어로 :

   lark-mcp mcp -a cli_xxxx -s yyyyy -l zh

   참고 : 언어를 중국어( -l zh )로 설정하면 토큰 사용량이 늘어날 수 있습니다. 대규모 언어 모델과 통합할 때 토큰 제한 문제가 발생하면 기본 영어 설정( -l en )을 사용하는 것이 좋습니다.

8. 도구 이름 형식을 Camel Case로 설정 :

   lark-mcp mcp -a cli_xxxx -s yyyyy -c camel

   참고 : 도구 이름 형식을 설정하면 MCP에 도구 이름이 표시되는 방식을 변경할 수 있습니다. 예를 들어, im.v1.message.create 다른 형식으로 변경할 수 있습니다.

   • 뱀 형식(기본값): im_v1_message_create

   • camel 형식: imV1MessageCreate

   • 케밥 형식: im-v1-message-create

   • dot 형식: im.v1.message.create

9. 명령줄 매개변수 대신 환경 변수 사용 :

   # Set environment variables export APP_ID=cli_xxxx export APP_SECRET=yyyyy # Start the service (no need to specify -a and -s parameters) lark-mcp mcp

10. 구성 파일 사용 :

명령줄 매개변수 외에도 JSON 형식 구성 파일을 사용하여 매개변수를 설정할 수 있습니다.

구성 파일 예(config.json):

참고 : 명령줄 매개변수는 구성 파일보다 우선합니다. 명령줄 매개변수와 구성 파일을 모두 사용하는 경우, 명령줄 매개변수가 구성 파일의 해당 설정보다 우선합니다.

11. 운송 모드 :

lark-mcp는 두 가지 전송 모드를 지원합니다.

1. stdio 모드(기본값/권장) : Trae/Cursor나 Claude와 같은 AI 도구와의 통합에 적합하며 표준 입출력 스트림을 통해 통신합니다.

2. SSE 모드 : 로컬 실행이 불가능한 시나리오에 적합한, 서버에서 보낸 이벤트 기반의 HTTP 인터페이스를 제공합니다.

시작 후 SSE 엔드포인트는 http://<host>:<port>/sse 에서 액세스할 수 있습니다.

자주 묻는 질문

• 문제 : Feishu/Lark API에 연결할 수 없습니다. 해결 방법 : 네트워크 연결을 확인하고 APP_ID와 APP_SECRET이 올바른지 확인하세요. Feishu/Lark 오픈 플랫폼 API에 액세스할 수 있는지 확인하세요. 프록시를 구성해야 할 수도 있습니다.

• 문제 : user_access_token 사용 시 오류 발생. 해결 방법 : 토큰이 만료되었는지 확인하세요. user_access_token은 일반적으로 2시간 동안 유효하며 주기적으로 갱신해야 합니다. 자동 토큰 갱신 메커니즘을 구현할 수 있습니다.

• 문제 : MCP 서비스 시작 후 특정 API를 호출할 수 없으며 권한 부족 오류가 발생합니다. 해결 방법 : 애플리케이션이 해당 API 권한을 획득했는지 확인하세요. 일부 API에는 개발자 콘솔 또는 Lark 개발자 콘솔 에서 구성할 수 있는 추가 상위 권한이 필요합니다. 권한이 승인되었는지 확인하세요.

• 문제 : 이미지 또는 파일 업로드/다운로드 관련 API 호출 실패 해결 방법 : 현재 버전은 파일 및 이미지 업로드/다운로드 기능을 지원하지 않습니다. 이러한 API는 향후 버전에서 지원될 예정입니다.

• 문제 : Windows 환경에서 명령줄에 깨진 문자가 표시됩니다. 해결 방법 : 명령 프롬프트에서 chcp 65001 실행하여 명령줄 인코딩을 UTF-8로 변경하세요. PowerShell을 사용하는 경우 터미널 글꼴이나 PowerShell 구성을 변경해야 할 수 있습니다.

• 문제 : 설치 중 권한 오류 해결 방법 : macOS/Linux에서는 sudo npm install -g @larksuiteoapi/lark-mcp 사용하여 설치하거나 npm 전역 설치 경로의 권한을 수정하세요. Windows 사용자는 명령 프롬프트를 관리자 권한으로 실행해 보세요.

• 문제 : MCP 서비스를 시작한 후 토큰 제한이 초과되었습니다. 해결 방법 : -t 사용하여 활성화된 API 수를 줄이거나 더 큰 토큰을 지원하는 모델(예: claude3.7)을 사용해 보세요.

• 문제 : SSE 모드에서 메시지를 연결하거나 수신할 수 없습니다. 해결 방법 : 포트가 이미 사용 중인지 확인하고 다른 포트로 변경해 보세요. 클라이언트가 SSE 엔드포인트에 올바르게 연결되어 있고 이벤트 스트림을 처리하고 있는지 확인하세요.

관련 링크

• Feishu 오픈 플랫폼

• Lark International 오픈 플랫폼

• Feishu 개방형 플랫폼 API 문서

• Lark 오픈 플랫폼 API 문서

• Node.js 웹사이트

• npm 문서

피드백

이 도구를 개선하는 데 도움이 되는 문제점을 알려주시면 감사하겠습니다. 질문이나 제안 사항이 있으시면 GitHub 저장소에 올려주세요.