Skip to main content
Glama
worksmobile-mcp

worksmobile-mcp

by z0nam

worksmobile-mcp

非官方 NAVER WORKS (LINE WORKS) Drive 管理 CLI + MCP 服务器,基于开发者 API 的服务账号委派(JWT delegated_user)构建。

现有的 WORKS MCP 服务器专注于最终用户层面(通过 User OAuth 访问你自己的邮件/日历/文件)。本项目覆盖它们所不具备的管理层面:

  • 通过委派以租户中任何成员的身份操作(类似 Google 全域委派)

  • 共享驱动器治理:列出驱动器,检查 accessibleRange/permissionType,授予/撤销驱动器和文件夹级权限,切换文件夹继承(enable/disable)

  • share-create(“与我共享”快捷方式)、My Drive 脚手架、上传/下载、搜索

  • 目录审计:账号卫生规则以及与外部名册的对账——找出仍拥有有效邮件/驱动器访问权限的前员工

与 NAVER / WORKS MOBILE Corp. 无关联。“NAVER WORKS”、“LINE WORKS”和 worksmobile.com 是其商标/财产。官方 API 文档:https://developers.worksmobile.com/

🙋 只想自己使用 WORKS?那这个工具不适合你。

如果你想让 AI 代理读取你自己的邮件、日历、驱动器或任务,请到此为止——参见 docs/END_USER_SETUP.md。该路径只需几分钟,不需要管理员权限,而且只会触及你自己的账号。

本项目面向租户管理员。它使用一个委派服务账号进行身份验证,该账号可以以组织中任何成员的身份操作,因此它需要的凭据是普通成员无法获取的。如果你的开发者控制台显示*“you do not have access”*,那不是需要解决的设置问题——而是边界按预期工作。

安全设计

🔑 在除自己机器以外的任何地方运行之前,请先阅读此内容

这不是按用户集成的工具。它所需的凭据是一个委派服务账号,可以以你租户中任何成员的身份操作——读取任何人的驱动器,更改任何人的共享设置。请像对待域管理员密钥一样对待私钥,因为它就是。

不要将这些凭据粘贴到第三方 MCP 托管、“install/deploy this server”按钮或托管检查器中,无论多么方便。这些会在别人的机器上运行服务器,而把此密钥交给他们就等于交出整个租户。本仓库的目录和市场列表是自动抓取的结果,不代表对任何部署模式的认可——本项目支持的唯一配置是在管理员自己的机器上运行本地 stdio。

如果你确实需要 HTTP 传输,请将其绑定到 localhost,并在其前面加上真正的身份验证。这里的密钥泄露无法通过轮换密码来恢复:在开发者控制台撤销该密钥之前,持有者就是每一位员工。

WORKS Drive 权限 API 有不少坑。本工具将其固化:

  • 每个变更操作都需要明确确认 —— CLI:--yes(非交互式运行在没有它时会拒绝);MCP:confirm=true 参数。代理在设置之前应询问人类。

  • 批量权限删除(“all-delete”)完全不暴露 —— 其语义在 WORKS 各版本之间发生了翻转(仅限主管理员 vs 对所有人开放)。

  • 破坏性语义在工具文档中有明确说明:驱动器 accessibleRange 的 PATCH 转换会清除已授予的权限;文件夹 enable 会破坏继承;disable 会丢弃文件夹授权。

Related MCP server: google-workspace-mcp-server

设置

  1. 在开发者控制台中,创建一个具有服务账号委派的应用,记下 Client ID/Secret,创建服务账号,并下载私钥。授予 OAuth 范围(file、user.read)。

  2. 配置凭据:

pip install worksmobile-mcp        # or: uv tool install worksmobile-mcp
mkdir -p ~/.config/worksmobile
cp .env.example ~/.config/worksmobile/.env   # then fill in values

配置解析顺序:进程环境变量(WORKS_*)> $WORKS_ENV_FILE > ./.env > ~/.config/worksmobile/.env。

CLI

worksmobile doctor                              # what credentials/scopes actually work
worksmobile users --dept 연구                    # members (joint appointments preserved)
worksmobile find 홍길동                          # search by any substring
worksmobile audit --ignore shared-accounts.txt  # account-hygiene findings
worksmobile drift roster.tsv --name-col name    # reconcile against an external roster

worksmobile drives                              # list shared drives
worksmobile drive @2001000000xxxxxx             # accessibleRange / permissionType
worksmobile ls --sd @2001000000xxxxxx           # list files
worksmobile perms @2001000000xxxxxx --folder FID
worksmobile grant @2001000000xxxxxx --target pm@corp.com --type WRITE --folder FID --yes
worksmobile share FID --owner host@corp.com --to pm@corp.com --type WRITE --yes
worksmobile download FID --sd @2001000000xxxxxx -o report.hwp
worksmobile call GET /users/me/drive/files      # raw API escape hatch

所有读取命令都接受 --user someone@corp.com 参数,以该成员的身份操作。

MCP 服务器

stdio(本地代理——Claude Code、Codex、Cursor、Gemini CLI):

claude mcp add worksmobile -- worksmobile-mcp
{ "mcpServers": { "worksmobile": { "command": "worksmobile-mcp" } } }

Streamable HTTP —— 用于本地绑定的端点,并在前面加上你自己的身份验证,而不是交给托管提供商(参见顶部的提示框):

worksmobile-mcp --transport streamable-http --host 127.0.0.1 --port 8123

⚠️ 无论你选择哪种传输方式,该进程都持有租户级管理员凭据——请在你运行域管理员 shell 的地方运行它,而不是其他地方。

工具

工具

变更

描述

works_drives_list / works_drive_get

共享驱动器及设置

works_files_list

共享驱动器或成员 My Drive 中的文件

works_perms_list

驱动器/文件夹权限

works_perm_grant / works_perm_revoke

⚠

授予/删除一条权限

works_folder_enable / works_folder_disable

⚠

文件夹继承开关

works_file_download / works_file_upload

存储重定向下载 / 两步上传

works_folder_create

My Drive 文件夹

works_share_create / works_share_delete

⚠

“与我共享”快捷方式(仅 My Drive)

works_sharedfolders_list

成员收到的共享

works_search

驱动器搜索

works_users_list / works_user_find

租户成员(需要 user.read)

works_directory_audit

账号卫生发现 + 休眠检查报告

works_directory_drift

对照外部名册对账账号

works_member_footprint

单个成员的完整触达范围——离职查询

works_api_call

⚠

原始 API 逃生舱

⚠ = 需要 confirm=true。

目录审计:休眠检查

works_directory_audit 在返回 findings 的同时返回 dormant_rules。当某条规则读取的字段在整个租户中为空时,该规则即处于休眠状态——例如,如果没有任何人的 leaveOfAbsence 被设置过,“休假但未暂停”就永远不会触发。空的 findings 列表并不代表一切健康,因此该工具会说明哪些检查无能为力,而不是暗示所有检查都已通过。coverage 显示每个字段的填充率。

这在实践中很重要:在构建此工具所针对的租户上,employeeNumber 为 0/136,hiredDate 为 1/136——HR 字段根本没有被填充,而这正是审计工具必须告诉你、而不是掩盖的事情。

对账:不在某个名册中并不构成证据

works_directory_drift 返回 only_works——即在你传入的名册中没有记录的账号。那是一个信号,而不是离职的证明。 每个名册都会遗漏某些人群:HR 登记册可能完全不包含访问研究员;聊天目录无法容纳从未被分配企业邮件的人。把“不在此列表中”解读为“已离职”,正是导致在职员工账号被删除的原因——这确实发生过一次,也是该工具现在这样工作的原因。

传入 corroborating_rosters({label: path}),包含你拥有的所有其他名册。在其他地方找到的行会以 seen_in 填充的形式返回,应从怀疑列表中剔除。每个名册都按电子邮件、电话和姓名建立索引,因为没有任何单一键是足够的——在促成此设计的真实案例中,该成员的账号上没有电话,也没有企业邮件,因此只有姓名匹配。

一个值得了解的陷阱:通过去掉 82 来规范化韩国手机号是错误的。许多记录同时带有国家代码和首位零(+82 010-…),因此仅去掉会得到 00…,什么都匹配不上——某个租户 40% 的号码都是如此。请使用 directory.norm_phone。

blind_spots 涵盖更困难的情况:API 完全无法回答的问题。最棘手的是委派管理员——isAdministrator 仅对 SUPER 管理员为 true,因此控制台中作为子管理员的账号仍报告 false。仅凭此 API 枚举“谁拥有管理员权限”会静默遗漏他们;请在管理控制台中进行该操作。

离职流程:在暂停账号之前收集足迹

works_member_footprint 一次调用即可回答“此人能触达什么”。它编码了两件容易出错的事情:

  • 顺序。 先暂停账号是直觉上的做法,但这会破坏你调查的能力:对已暂停账号的委派会失败,因此他们的 My Drive 内容和收到的文件夹将无法访问。先收集,后暂停。

  • 驱动器 master 在 /permissions 中不可见。 它们位于共享驱动器对象的 masters[] 中。master 可以授予权限和更改驱动器设置,因此在交接中遗漏它们会使驱动器实际上处于无主状态——该工具会单独报告它们。

API 说明(来之不易的经验)

  • accessibleRange 有 3 个值:TENANT / DOMAIN / MEMBER。新驱动器默认为 DOMAIN+WRITE。PATCH 转换具有破坏性(MEMBER→DOMAIN 会删除所有授权;存在文件夹级授权时 →MEMBER 会失败)。

  • 文件夹级权限仅接受单个用户(不支持组织单元);目标用户必须已经是驱动器成员(未记录,观察所得)。

  • 文件夹 enable = 在授予之前仅限 master;disable = 丢弃授权,恢复继承。

  • share-create 仅适用于 My Drive 文件夹——团队驱动器文件夹无法生成“与我共享”快捷方式。

  • 纯服务账号令牌没有 My Drive(403);托管需要委派给真实账号。

  • 上传分两步(元数据 POST → uploadUrl PUT);下载是 302 重定向,其存储位置同样需要 Bearer 令牌。

  • GET /sharedrives 返回 {"sharedrives": [...]}(文档暗示是裸数组)。

许可证

MIT

Available Tools

16 tools
works_api_callB

Raw WORKS API escape hatch (path under https://www.worksapis.com/v1.0). Non-GET requires confirm=true.

Inputs: path (required), method (required), user, confirm, +1 more.

works_drive_getB

Get one shared drive's settings (accessibleRange TENANT/DOMAIN/MEMBER, permissionType).

Inputs: sharedrive_id (required), user.

works_drives_listB

List shared drives (id, name, accessibleRange, permissionType, masters).

Inputs: user.

works_file_downloadA

Download a file to a local path (follows the storage redirect with auth).

Inputs: file_id (required), out_path (required), user, sharedrive_id.

works_files_listB

List files/folders. With sharedrive_id: that shared drive; else the delegated user's My Drive.

Inputs: user, folder_id, sharedrive_id.

works_file_uploadB

Upload a local file into a My Drive folder (2-step metadata+PUT flow).

Inputs: file_path (required), parent_folder_id (required), name, user.

works_folder_createA

Create a folder in the delegated user's My Drive (root if no parent).

Inputs: name (required), user, parent_folder_id.

works_folder_disableA

Disable folder-level permissions. WARNING: drops folder grants, restores inheritance. Requires confirm=true.

Inputs: folder_id (required), sharedrive_id (required), user, confirm.

works_folder_enableA

Enable folder-level permissions. WARNING: breaks inheritance (masters-only until granted). Requires confirm=true.

Inputs: folder_id (required), sharedrive_id (required), user, confirm.

works_perm_grantA

Grant READ/WRITE to a member (drive-level, or folder-level with folder_id). Requires confirm=true.

Inputs: perm_type (required), target_email (required), sharedrive_id (required), user, +2 more.

works_perm_revokeA

Delete ONE permission by perm_id or target_email. Bulk delete is unsupported by design. Requires confirm=true.

Inputs: sharedrive_id (required), user, confirm, perm_id, +2 more.

works_perms_listA

List drive-level (or, with folder_id, folder-level) permissions.

Inputs: sharedrive_id (required), user, folder_id.

works_share_createA

Share a My Drive folder so it appears in the recipient's 'shared with me'. My Drive only (not shared drives). Requires confirm=true.

Inputs: file_id (required), to_email (required), owner_email (required), notify, +2 more.

works_share_deleteC

Remove sharing from a My Drive folder. Requires confirm=true.

Inputs: file_id (required), owner_email (required), confirm.

works_sharedfolders_listA

List a member's 'shared with me' folders (requires that member as delegated user).

Inputs: user (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 16 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes, with only minor potential overlap between works_share_create/works_perm_grant and works_files_list/works_search. The descriptions generally resolve ambiguity adequately.

    Naming Consistency4/5

    Tools follow a consistent noun_verb pattern (e.g., drive_get, files_list, perm_grant), with the exception of works_search, which lacks a resource prefix. This is a minor deviation from an otherwise predictable naming convention.

    Tool Count4/5

    16 tools is slightly above the typical 3-15 range, but the scope covers file management, permissions, sharing, and a raw API escape hatch. Each tool serves a distinct purpose, making the count reasonable for the apparent domain.

    Completeness3/5

    The toolkit covers listing, downloading, uploading, sharing, and permission management well, but lacks file delete, rename, move, and drive lifecycle operations (create/update/delete). These gaps are notable for a file management server.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers