lark-hermes-mcp

English · 简体中文

Feishu(飞书) / Lark 기능을 Hermes, Claude Desktop 또는 기타 MCP 호환 에이전트에 함수 도구로 노출하는 경량 MCP stdio 서버입니다.

• 17개의 폴백 도구 (수동 작성): 메시징, Bitable, 캘린더, 문서 및 작업 작업용

• 36개의 도구: @larksuite/openclaw-lark에서 shim 어댑터를 통해 브리지됨

• 4개의 OAuth 도구 (lark_oauth_start / lark_oauth_complete / lark_oauth_status / lark_oauth_revoke): 사용자 액세스 토큰 인증을 위한 OpenClaw의 Device Flow 구동

전송: stdio (stdout은 JSON-RPC 전용, pino 로그는 stderr로 출력) 인증: tenant_access_token + user-access-token (OAuth Device Flow) SDK: @larksuiteoapi/node-sdk + @larksuite/openclaw-lark

요구 사항

• Node.js ≥ 22

• 본인이 소유한 Feishu 또는 Lark 커스텀 앱 (自建应用)

• MCP 호환 클라이언트 (예: Hermes, Claude Desktop 또는 기타 stdio MCP 호스트)

Related MCP server: Feishu/Lark OpenAPI MCP

설치

1단계 — Feishu / Lark 앱 등록

이 프로젝트는 사전 등록된 앱 자격 증명을 제공하지 않습니다. 모든 사용자는 Feishu/Lark 오픈 플랫폼에서 직접 앱을 생성해야 합니다.

1. https://open.feishu.cn/app (중국 내 Feishu) 또는 https://open.larksuite.com/app (해외 Lark)에 접속합니다.

2. **"创建企业自建应用" / "Create Custom App"**을 클릭하고 이름과 아이콘을 설정합니다.

3. 생성 후 앱 대시보드를 엽니다:

   • 凭证与基础信息 / Credentials & Basic Info 페이지 → App ID (형식 cli_xxxxxxxxxxxxxxxx)와 App Secret을 복사합니다.

   • 权限管理 / Permissions & Scopes 페이지 → 사용할 스코프를 활성화합니다. 여기에 번들된 도구의 핵심 세트는 다음과 같습니다:

     • im:message, im:chat (메시징)

     • bitable:app (다차원 표)

     • docx:document, drive:drive (문서)

     • calendar:calendar (캘린더)

     • 작업 도구를 사용하려면 작업 관련 스코프를 추가합니다.

   • OAuth (user-access-token) 도구를 사용할 계획이라면 앱 설정에서 Device Flow / OAuth도 활성화하십시오. OAuth 도구는 런타임에 세부적인 API별 스코프를 요청합니다. 첫 호출 시 lark_oauth_start가 정확한 스코프 목록을 출력하므로 무엇을 활성화해야 할지 알 수 있습니다.

4. 앱 대시보드에서 앱 버전을 发布 / Publish하여 스코프가 적용되도록 합니다.

2단계 — 복제 및 설치

git clone https://github.com/WilliamMo101/lark-hermes-mcp.git
cd lark-hermes-mcp
npm install # triggers postinstall patches (see "Upstream & Patches" below)
npm run build

3단계 — 자격 증명 구성

독립형 (모든 MCP 호스트):

cp .env.example .env
# then edit .env and paste the App ID / App Secret you got in Step 1

.env 파일은 git-ignored 처리되어 커밋되지 않습니다.

Hermes 사용 시: .env 파일이 필요하지 않습니다. profiles/<your-agent>/config.yaml의 mcp_servers.lark.env 아래에 변수를 직접 입력하십시오:

mcp_servers:
 lark:
 command: /path/to/node
 args:
 - /path/to/lark-hermes-mcp/dist/server.js
 env:
 LARK_APP_ID: "cli_xxxxxxxxxxxxxxxx"
 LARK_APP_SECRET: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
 LARK_DOMAIN: "Feishu"
 LARK_ENABLED_TOOLSETS: "messaging,docs,bitable,calendar,other"
 LARK_LOG_LEVEL: "info"
 timeout: 120
 connect_timeout: 30
 tools:
 resources: false
 prompts: false

LARK_DOMAIN: 중국 내 Feishu는 Feishu, 해외 Lark는 Lark로 설정합니다. 잘못된 값은 OAuth 서비스에서 거부(invalid_client)됩니다.

**LARK_ENABLED_TOOLSETS**에 OAuth 도구(lark_oauth_*)와 작업 도구를 노출하려면 other가 포함되어야 합니다.

4단계 — 실행 및 확인

node dist/server.js # starts the stdio MCP server

또는 MCP 호스트에 연결하고 feishu_get_user 또는 lark_oauth_status를 호출하여 스모크 테스트를 수행하십시오.

Hermes는 도구를 mcp_lark_<name>으로 노출합니다 (언더스코어 사용, mcp_tool.py:sanitize_mcp_name_component 기준).

이 README의 예시 경로(이전 스니펫의 /root/.hermes/mcp-servers/… 등)는 작성자의 WSL 환경 Hermes 레이아웃을 반영합니다. 저장소를 체크아웃한 위치에 맞게 조정하십시오.

폴백 도구 (17개)

src/adapter/fallback.ts에 수동으로 작성된 사양입니다:

OpenClaw 브리지 도구 (36개)

src/adapter/shim.ts는 @larksuite/openclaw-lark의 내부 등록에 대해 registerXxxTools(api)를 호출하고, 각 도구를 Typebox → JSON Schema 평탄화(OpenAI 함수 호출 호환성을 위해)로 래핑하며, AsyncLocalStorage를 통해 withTicket 컨텍스트를 주입합니다.

도구는 feishu_ / mcp_doc_ 접두사와 함께 나타납니다 (예: feishu_bitable_app, feishu_calendar_event, feishu_im_chat_messages).

OAuth 도구 (4개)

• lark_oauth_start — Device Flow 시작 (user_code + 인증 URL 출력)

• lark_oauth_complete — 사용자가 브라우저에서 승인한 후 토큰 폴링

• lark_oauth_status — 저장된 사용자 토큰 상태 확인 (유효함 / 갱신 필요 / 만료됨)

• lark_oauth_revoke — 저장된 사용자 토큰 취소

토큰은 암호화(AES-256-GCM)되어 ~/.local/share/openclaw-feishu-uat/에 저장됩니다.

스모크 테스트 (MCP 호스트 없이 독립 실행)

export LARK_APP_ID=cli_xxx LARK_APP_SECRET=xxx LARK_DOMAIN=Feishu
(
 echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}'
 echo '{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}'
 echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
 echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"selfCheck","arguments":{}}}'
) | node dist/server.js 2>/tmp/lark-mcp.err > /tmp/lark-mcp.out
jq '.result.tools | length' < /tmp/lark-mcp.out
jq 'select(.id==3)' < /tmp/lark-mcp.out

Shim에 대한 등록 횟수 스모크 테스트도 있습니다:

LARK_APP_ID=cli_xxx node scripts/shim-smoke.mjs

업스트림 및 패치

이 프로젝트는 @larksuite/openclaw-lark (MIT 라이선스)를 기반으로 구축되었습니다. 노출된 도구 중 36개는 src/adapter/shim.ts를 통해 네이티브 도구 등록에서 직접 브리지됩니다.

scripts/postinstall-patches.mjs는 npm install 후 자동으로 실행되며 node_modules/@larksuite/openclaw-lark/ 내부에 멱등성(idempotent) 패치를 적용하여 Node 22 CJS 환경에서 패키지가 깔끔하게 로드되도록 합니다:

1. version.js에서 import.meta.url 구문을 제거 (createRequire 기반 해결책으로 대체).

2. token-store.js에 동일한 처리 적용.

3. @openclaw/plugin-sdk에 대한 최소 스텁 빌드 (등록 시 실제로 가져오는 부분만).

4. 패키지의 exports 맵을 확장하여 심층적인 ./src/* 가져오기가 해결되도록 함.

이 패치들은 로컬 node_modules/ 내부의 파일만 수정합니다. 업스트림 소스는 수정되지 않으며, 패치는 모든 설치 시 안전하게 다시 실행됩니다.

문제 해결

• 호스트의 도구 목록에 아무것도 없음 — 호스트 로그에서 MCP server 'lark'를 grep하십시오. 일반적인 원인:

  • LARK_APP_ID / LARK_APP_SECRET이 전달되지 않음 — 호스트가 허용 목록 환경 변수를 사용하는 경우 셸 내보내기가 전파되지 않습니다. 대신 MCP 구성 블록에 선언하십시오.

  • dist/server.js 누락 — npm run build를 실행하십시오.

  • 잘못된 node 바이너리 — Node ≥ 22여야 합니다.

• 도구 목록에서 OAuth 도구 누락 — LARK_ENABLED_TOOLSETS에 other가 포함되어야 합니다.

• lark_oauth_start에서 invalid_scope 발생 — 요청된 스코프 중 하나가 앱에서 아직 승인되지 않았습니다. 앱의 권한 페이지를 열고 오류에 나열된 스코프를 활성화한 후 새 버전을 게시하십시오.

• OAuth에서 invalid_client 발생 — 앱 지역에 대해 LARK_DOMAIN이 잘못되었습니다 (중국 내 = Feishu, 해외 = Lark).

• stdout 오염 (MCP 클라이언트가 즉시 연결 해제됨) — 일부 타사 라이브러리가 stdout에 기록했습니다. stderr 로그를 확인하십시오. server.ts는 이미 console.*을 가로채며 pino는 stderr에 기록합니다.

• 클라이언트 측 속도 제한 — 환경 변수를 통해 LARK_THROTTLE_BITABLE_RPS 등을 조정하십시오.

프로젝트 레이아웃

src/
 server.ts # MCP entry, console hijack, handlers
 auth.ts # @larksuiteoapi/node-sdk Client factory
 log.ts # pino → stderr
 toolsets.ts # toolset enum + env filter
 util/throttle.ts # per-toolset token bucket
 adapter/
 index.ts # tool loader + toolset filter
 fallback.ts # 17 hand-written fallback tool specs
 shim.ts # OpenClaw bridge + schema flattening
 oauth-tools.ts # 4 OAuth tools (Device Flow)
scripts/
 postinstall-patches.mjs # idempotent node_modules patches
 shim-smoke.mjs # registration-count smoke test

크레딧

• @larksuite/openclaw-lark by OpenClaw — MIT 라이선스. 이 프로젝트는 이를 래핑하고 의존합니다.

• Model Context Protocol SDK by Anthropic.

• Feishu / Lark 오픈 플랫폼 API.

면책 조항

이 프로젝트는 개인 취미 프로젝트이며, 어떠한 보증 없이 '있는 그대로' 제공됩니다. Feishu, Lark, ByteDance 또는 OpenClaw의 공식 제품이 아닙니다.

这是一个个人兴趣项目，按"现状"提供，不附带任何担保。本项目与飞书/Lark、 字节跳动、OpenClaw 官方团队无隶属关系，出现问题请通过 GitHub Issues 反馈。

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers

Tools

• bitableCreateRecordB
• bitableListRecordsC
• bitableUpdateRecordC
• calendarCreateEventC
• calendarListCalendarsC
• calendarListEventsC
• docxGetRawContentC
• docxListBlocksC