worksmobile-mcp

Unofficial NAVER WORKS (LINE WORKS) Drive admin CLI + MCP server, built on the Developer API's service-account delegation (JWT delegated_user).

Existing WORKS MCP servers focus on the end-user plane (your own mail/calendar/files via User OAuth). This project covers the admin plane that they don't:

• act as any member of your tenant via delegation (like Google domain-wide delegation)
• shared-drive governance: list drives, inspect accessibleRange/permissionType, grant/revoke drive- and folder-level permissions, toggle folder inheritance (enable/disable)
• share-create ("shared with me" shortcuts), My Drive scaffolding, upload/download, search
• directory audit: account-hygiene rules and reconciliation against an external roster — find ex-employees who still hold live mail/drive access

Not affiliated with NAVER / WORKS MOBILE Corp. "NAVER WORKS", "LINE WORKS" and worksmobile.com are their trademarks/properties. Official API docs: https://developers.worksmobile.com/

🙋 Just want to use WORKS yourself? This is the wrong tool.

If you want an AI agent to read your own mail, calendar, drive or tasks, stop here — see docs/END_USER_SETUP.md. That path takes minutes, needs no admin rights, and only ever touches your own account.

This project is for tenant administrators. It authenticates with a delegated service account that can act as any member of the organization, which is why it needs credentials a normal member cannot get. If your Developer Console says "you do not have access", that is not a setup problem to solve — it is the boundary working as intended.

Safety design

🔑 Read this before you run it anywhere but your own machine

This is not a per-user integration. The credential it takes is a delegated service account that can act as any member of your tenant — read anyone's drive, change anyone's sharing. Treat the private key like a domain-admin key, because that is what it is.

Do not paste these credentials into third-party MCP hosting, an "install/deploy this server" button, or a hosted inspector, however convenient. Those run the server on someone else's machine, and handing them this key hands over the whole tenant. Directory and marketplace listings of this repo are automated crawls, not endorsements of any deployment model — the only configuration this project supports is local stdio, on the administrator's own machine.

If you genuinely need the HTTP transport, bind it to localhost and put real authentication in front of it. Key compromise here is not recoverable by rotating a password: until the key is revoked in the Developer Console, the holder is every employee.

WORKS Drive permission APIs have sharp edges. This tool encodes them:

• Every mutating operation requires explicit confirmation — CLI: --yes (non-interactive runs refuse without it); MCP: confirm=true parameter. Agents are expected to ask the human before setting it.
• Bulk permission delete ("all-delete") is not exposed at all — its semantics flipped between WORKS versions (masters-only vs open to everyone).
• Destructive semantics are spelled out in tool docs: drive accessibleRange PATCH transitions wipe granted permissions; folder enable breaks inheritance; disable drops folder grants.

Setup

1. In the Developer Console, create an app with service-account delegation, note Client ID/Secret, create the service account, and download the private key. Grant OAuth scopes (file, user.read).
2. Configure credentials:

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

Config resolution: process env (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

All read commands accept --user someone@corp.com to act as that member.

MCP server

stdio (local agents — Claude Code, Codex, Cursor, Gemini CLI):

claude mcp add worksmobile -- worksmobile-mcp

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

Streamable HTTP — for a locally bound endpoint you front with your own auth, not for handing to a hosting provider (see the box at the top):

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

⚠️ Whichever transport you pick, the process holds a tenant-wide admin credential — run it where you would run a domain-admin shell, and nowhere else.

Tools

Tool	Mutating	Description
works_drives_list / works_drive_get		shared drives & settings
works_files_list		files of a shared drive or a member's My Drive
works_perms_list		drive/folder permissions
works_perm_grant / works_perm_revoke	⚠	grant / delete one permission
works_folder_enable / works_folder_disable	⚠	folder inheritance gate
works_file_download / works_file_upload		storage-redirect download / 2-step upload
works_folder_create		My Drive folder
works_share_create / works_share_delete	⚠	"shared with me" shortcuts (My Drive only)
works_sharedfolders_list		a member's received shares
works_search		drive search
works_users_list / works_user_find		tenant members (needs user.read)
works_directory_audit		account-hygiene findings + dormant-check report
works_directory_drift		reconcile accounts against an external roster
works_member_footprint		one member's full reach — the offboarding query
works_api_call	⚠	raw API escape hatch

⚠ = requires confirm=true.

Directory audit: dormant checks

works_directory_audit returns dormant_rules alongside findings. A rule is dormant when the field it reads is empty across the whole tenant — e.g. if nobody's leaveOfAbsence is ever set, "on leave but not suspended" can never fire. An empty findings list is not a clean bill of health, so the tool says which checks were powerless instead of implying everything passed. coverage shows the fill rate per field.

This matters in practice: on the tenant this was built against, employeeNumber was 0/136 and hiredDate 1/136 — the HR fields simply were not populated, which is exactly the kind of thing an audit tool must tell you rather than paper over.

Reconciliation: absence from one roster is not evidence

works_directory_drift returns only_works — accounts with no entry in the roster you passed. That is a signal, not proof of departure. Every roster omits some population: an HR register may not carry visiting researchers at all; a chat directory cannot hold people who were never issued corporate mail. Reading "not in this list" as "has left" is how a current employee loses their account — which is exactly what happened once, and why the tool now works this way.

Pass corroborating_rosters ({label: path}) with every other roster you have. Rows found elsewhere come back with seen_in populated and should be dropped from suspicion. Each roster is indexed by email, phone and name, because no single key is enough — in the real case that motivated this, the member had no phone on their account and no corporate mail, so only the name matched.

One trap worth knowing: normalising Korean mobile numbers by stripping 82 is wrong. Many records carry the country code and the trunk zero (+82 010-…), so stripping alone yields 00… and matches nothing — 40% of one tenant's numbers. Use directory.norm_phone.

blind_spots covers the harder case: questions the API cannot answer at all. The one that bites is delegated administrators — isAdministrator is true only for SUPER admins, so an account that is a sub-admin in the console still reports false. Enumerating "who has admin rights" from this API alone will silently miss them; do that in the admin console.

Offboarding: collect the footprint before you suspend

works_member_footprint answers "what can this person reach" in one call. Two things it encodes that are easy to get wrong:

• Order. Suspending the account first is the intuitive move and it destroys your ability to investigate: delegation to a suspended account fails, so their My Drive contents and received folders become unreachable. Collect first, suspend second.
• Drive masters are invisible in /permissions. They live on the shared-drive object's masters[]. A master can grant permissions and change drive settings, so missing them in a handover leaves the drive effectively ownerless — the tool reports them separately.

API notes (hard-won)

• accessibleRange is 3-valued: TENANT / DOMAIN / MEMBER. New drives default to DOMAIN+WRITE. PATCH transitions are destructive (MEMBER→DOMAIN deletes all grants; →MEMBER fails while folder-level grants exist).
• Folder-level permissions accept individual users only (no org units); the target must already be a drive member (undocumented, observed).
• Folder enable = masters-only until you grant; disable = grants dropped, inheritance back.
• share-create works on My Drive folders only — team-drive folders can't produce "shared with me" shortcuts.
• A pure service-account token has no My Drive (403); hosting requires delegation to a real account.
• Upload is 2-step (metadata POST → uploadUrl PUT); download is a 302 whose storage location also requires the Bearer token.
• GET /sharedrives responds {"sharedrives": [...]} (docs imply a bare array).

License

MIT