worksmobile-mcp
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
设置
在开发者控制台中,创建一个具有服务账号委派的应用,记下 Client ID/Secret,创建服务账号,并下载私钥。授予 OAuth 范围(
file、user.read)。配置凭据:
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 的地方运行它,而不是其他地方。
工具
工具 | 变更 | 描述 |
| 共享驱动器及设置 | |
| 共享驱动器或成员 My Drive 中的文件 | |
| 驱动器/文件夹权限 | |
| ⚠ | 授予/删除一条权限 |
| ⚠ | 文件夹继承开关 |
| 存储重定向下载 / 两步上传 | |
| My Drive 文件夹 | |
| ⚠ | “与我共享”快捷方式(仅 My Drive) |
| 成员收到的共享 | |
| 驱动器搜索 | |
| 租户成员(需要 | |
| 账号卫生发现 + 休眠检查报告 | |
| 对照外部名册对账账号 | |
| 单个成员的完整触达范围——离职查询 | |
| ⚠ | 原始 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 →
uploadUrlPUT);下载是 302 重定向,其存储位置同样需要 Bearer 令牌。GET /sharedrives返回{"sharedrives": [...]}(文档暗示是裸数组)。
许可证
MIT
Available Tools
16 toolsworks_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_searchC
Search drive files (drive_type_filters e.g. 'SHARE_DRIVE').
Inputs: query (required), user, drive_type_filters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
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.
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.
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.
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
Related MCP Connectors
Linux server administration over OAuth MCP: shell, Docker, systemd, files and monitoring.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
The official MCP Server from Mia-Platform to interact with Mia-Platform Console
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- AlicenseAqualityCmaintenanceSelf-hosted MCP server that exposes Synology Drive, Spreadsheet, MailPlus, and Calendar as structured tools for AI agents, enabling file, spreadsheet, email, and calendar management via natural language.3913 npm11MIT
- AlicenseAqualityDmaintenanceMCP server for Google Workspace APIs - Docs, Sheets, Drive, Gmail, and Calendar. Enables reading, creating, and editing Google Docs and Sheets, managing comments, reading emails, and viewing calendar events.3417MIT
- AlicenseBqualityDmaintenanceProduction-ready MCP server for Google Workspace providing broad coverage across Gmail, Drive, Calendar, Docs, Sheets, and more, with safe-by-default write operations and markdown-to-Google-Docs support.10039 PyPIMIT
- AlicenseAqualityCmaintenanceMCP server for interacting with Google Drive using a service account, restricted to a specific root folder. Supports file operations like search, list, create, update, and read.412 npm1MIT