Integrations
Provides a Node.js-based MCP server that encapsulates Feishu/Lark Open Platform API interfaces, allowing AI assistants to directly call these interfaces for various automation scenarios.
페이슈/라크 OpenAPI 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 인터페이스를 캡슐화합니다.
- 이중 인증 지원:
- 앱 액세스 토큰 인증을 지원합니다
- 사용자 액세스 토큰 인증을 지원합니다
- 유연한 통신 프로토콜:
- Cursor/Claude와 같은 AI 도구와의 통합에 적합한 표준 입출력 스트림(stdio) 모드를 지원합니다.
- HTTP 기반 인터페이스를 제공하는 SSE(Server-Sent Events) 모드를 지원합니다.
- 다양한 사용 시나리오에 맞춰 여러 구성 방법을 지원합니다.
도구 목록
지원되는 모든 Feishu/Lark 도구의 전체 목록은 tools.md 에서 확인할 수 있으며, 여기서 도구는 설명과 함께 프로젝트 및 버전별로 분류됩니다.
준비
Feishu/Lark 애플리케이션 만들기
lark-mcp 도구를 사용하기 전에 Feishu/Lark 애플리케이션을 만들어야 합니다.
- Feishu Open Platform 또는 Lark Open Platform을 방문하여 로그인하세요.
- "시작하기"를 클릭하고 새 애플리케이션을 만드세요
- API 인증에 사용될 앱 ID와 앱 비밀번호를 얻으세요.
- 사용 시나리오에 따라 애플리케이션에 필요한 권한을 추가하세요.
- 사용자로서 API를 호출해야 하는 경우 OAuth 2.0 리디렉션 URL을 설정하고 사용자 액세스 토큰을 얻으세요.
자세한 애플리케이션 생성 및 구성 지침은 Feishu 오픈 플랫폼 문서 - 애플리케이션 생성 또는 Lark 오픈 플랫폼 문서를 참조하세요.
Node.js 설치
lark-mcp 도구를 사용하기 전에 Node.js 환경을 설치해야 합니다.
macOS에 Node.js 설치
- Homebrew 사용(권장) :지엑스피1
- 공식 설치 프로그램 사용 :
- Node.js 웹사이트를 방문하세요
- LTS 버전을 다운로드하고 설치하세요
- 설치 후 터미널에서 확인하세요.Copy
Windows에 Node.js 설치
- 공식 설치 프로그램 사용 :
- Node.js 웹사이트를 방문하세요
- Windows 설치 프로그램(.msi 파일)을 다운로드하여 실행하세요.
- 설치 마법사를 따라 설치를 완료하세요.
- 설치 후 명령 프롬프트에서 확인하세요.Copy
- nvm-windows 사용하기 :
- nvm-windows 다운로드
- nvm-windows 설치
- nvm을 사용하여 Node.js를 설치하세요.Copy
설치
lark-mcp 도구를 전역적으로 설치합니다.
사용 가이드
Cursor/Claude와 함께 사용
Cursor나 Claude와 같은 AI 도구에 Feishu/Lark 기능을 통합하려면 구성 파일에 다음을 추가하세요.
사용자 ID로 API에 액세스하려면 사용자 액세스 토큰을 추가할 수 있습니다.
고급 구성
명령줄 매개변수
lark-mcp 도구는 유연한 MCP 서비스 구성을 위한 다양한 명령줄 매개변수를 제공합니다.
| 매개변수 | 짧은 | 설명 | 예 |
|---|---|---|---|
--app-id | -a | Feishu/Lark 애플리케이션 앱 ID | -a cli_xxxx |
--app-secret | -s | 페이슈/라크 앱 앱 시크릿 | -s xxxx |
--domain | -d | Feishu/Lark API 도메인, 기본값은 Feishu 중국 버전입니다. | -d https://open.larksuite.com |
--tools | -t | 쉼표로 구분된 활성화할 API 도구 목록 | -t im.v1.message.create,im.v1.chat.create |
--tool-name-case | -c | 도구 이름 형식, 옵션은 뱀, 낙타, 점 또는 케밥이며 기본값은 뱀입니다. | -c camel |
--language | -l | 도구 언어, 옵션은 zh 또는 en이며 기본값은 en입니다. | -l zh |
--user-access-token | -u | 사용자로서 API를 호출하기 위한 사용자 액세스 토큰 | -u u-xxxx |
--mode | -m | 전송 모드, 옵션은 stdio 또는 sse이며 기본값은 stdio입니다. | -m sse |
--host | SSE 모드에서 수신 호스트, 기본값은 localhost입니다. | --host 0.0.0.0 | |
--port | -p | SSE 모드에서 수신 포트, 기본값은 3000입니다. | -p 3000 |
--config | 구성 파일 경로, JSON 형식 지원 | --config ./config.json | |
--version | -V | 버전 번호 표시 | -V |
--help | -h | 도움말 정보 표시 | -h |
매개변수 사용 예
- 기본 사용법 (애플리케이션 ID 사용):Copy
- 사용자 ID 사용 :Copy
- Lark International 도메인 지정 :Copy
- 특정 API 도구만 활성화하기 :Copy
- 특정 포트 및 호스트를 사용하여 SSE 모드 사용 :Copy
- 설정 도구 언어를 중국어로 :Copy
참고 : 언어를 중국어(
-l zh)로 설정하면 토큰 사용량이 늘어날 수 있습니다. 대규모 언어 모델과 통합할 때 토큰 제한 문제가 발생하면 기본 영어 설정(-l en)을 사용하는 것이 좋습니다. - 도구 이름 형식을 Camel Case로 설정 :Copy
참고 : 도구 이름 형식을 설정하면 MCP에 도구 이름이 표시되는 방식을 변경할 수 있습니다. 예를 들어,
im.v1.message.create다른 형식으로 변경할 수 있습니다.- 뱀 형식(기본값):
im_v1_message_create - camel 형식:
imV1MessageCreate - 케밥 형식:
im-v1-message-create - dot 형식:
im.v1.message.create
- 뱀 형식(기본값):
- 명령줄 매개변수 대신 환경 변수 사용 :Copy
구성 파일 사용
명령줄 매개변수 외에도 JSON 형식 구성 파일을 사용하여 매개변수를 설정할 수 있습니다.
구성 파일 예(config.json):
참고 : 명령줄 매개변수는 구성 파일보다 우선합니다. 명령줄 매개변수와 구성 파일을 모두 사용하는 경우, 명령줄 매개변수가 구성 파일의 해당 설정보다 우선합니다.
사용자 액세스 토큰 사용
특정 사용자로 API를 호출해야 하는 경우 사용자 액세스 토큰을 지정하면 됩니다.
사용자 액세스 토큰은 Feishu Open Platform의 인증 절차 또는 Lark Open Platform의 인증 절차를 통해 획득하거나, API 디버깅 콘솔을 사용하여 획득할 수 있습니다. 사용자 액세스 토큰을 사용하면 해당 사용자의 ID를 사용하여 API 호출이 수행됩니다.
사용자 정의 도메인 지정
Lark 국제 버전이나 사용자 지정 도메인을 사용하는 경우 -d 매개변수를 사용하여 지정할 수 있습니다.
운송 모드
lark-mcp는 두 가지 전송 모드를 지원합니다.
- stdio 모드(기본값/권장) : Cursor나 Claude와 같은 AI 도구와의 통합에 적합하며 표준 입출력 스트림을 통해 통신합니다.Copy
- SSE 모드 : 웹 애플리케이션이나 네트워크 인터페이스가 필요한 시나리오에 적합한, 서버에서 보낸 이벤트 기반의 HTTP 인터페이스를 제공합니다.시작 후 SSE 엔드포인트는Copy
http://<host>:<port>/sse에서 액세스할 수 있습니다.
더 많은 API 활성화
기본적으로 MCP 서비스는 공통 API를 활성화합니다. 다른 도구나 특정 API만 활성화하려면 -t 매개변수(쉼표로 구분)를 사용하여 지정할 수 있습니다.
기본 지원 API 목록
기본적으로 MCP 서비스는 다음 API를 활성화합니다.
| 도구 이름 | 기능 설명 |
|---|---|
| im.v1.chat.create | 그룹 채팅 만들기 |
| im.v1.chat.list | 그룹 채팅 목록 가져오기 |
| im.v1.chatMembers.get | 그룹 멤버를 얻으세요 |
| im.v1.message.create | 메시지 보내기 |
| im.v1.메시지.목록 | 메시지 목록 가져오기 |
| wiki.v2.space.getNode | 위키 노드 가져오기 |
| 위키.v1.노드.검색 | 위키 노드 검색 |
| docx.v1.document.rawContent | 문서 내용 가져오기 |
| drive.v1.permissionMember.create | 공동작업자 권한 추가 |
| docx.builtin.import | 문서 가져오기 |
| docx.builtin.search | 문서 검색 |
| bitable.v1.app.create | Bitable 만들기 |
| bitable.v1.appTable.create | Bitable 데이터 테이블 만들기 |
| bitable.v1.appTable.list | Bitable 데이터 테이블 목록 가져오기 |
| bitable.v1.appTableField.list | Bitable 데이터 테이블 필드 목록 가져오기 |
| bitable.v1.appTableRecord.search | Bitable 데이터 테이블 레코드 검색 |
| bitable.v1.appTableRecord.create | Bitable 데이터 테이블 레코드 생성 |
| bitable.v1.appTableRecord.update | Bitable 데이터 테이블 레코드 업데이트 |
| 연락처.v3.user.batchGetId | 일괄 사용자 ID 가져오기 |
자주 묻는 질문
- 문제 : Feishu/Lark API에 연결할 수 없습니다. 해결 방법 : 네트워크 연결을 확인하고 APP_ID와 APP_SECRET이 올바른지 확인하세요. Feishu/Lark 오픈 플랫폼 API에 액세스할 수 있는지 확인하세요. 프록시를 구성해야 할 수도 있습니다.
- 문제 : user_access_token 사용 시 오류 발생. 해결 방법 : 토큰이 만료되었는지 확인하세요. user_access_token은 일반적으로 2시간 동안 유효하며 주기적으로 갱신해야 합니다. 자동 토큰 갱신 메커니즘을 구현하거나 app_access_token을 대신 사용할 수 있습니다.
- 문제 : 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 엔드포인트에 올바르게 연결되어 있고 이벤트 스트림을 처리하고 있는지 확인하세요.
관련 링크
피드백
이 도구를 개선하는 데 도움이 되는 문제점을 알려주시면 감사하겠습니다. 질문이나 제안 사항이 있으시면 GitHub 저장소에 올려주세요.
This server cannot be installed
AI 어시스턴트가 문서 처리, 대화 관리, 일정 예약과 같은 자동화 시나리오를 위해 Feishu/Lark API 인터페이스를 직접 호출할 수 있도록 하는 툴킷입니다.