Skip to main content
Glama
worksmobile-mcp

worksmobile-mcp

by z0nam

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

  • account state: suspend / restore / create members over SCIM β€” the one thing the Directory API cannot do, on a credential that cannot permanently delete anyone

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.

Related MCP server: google-workspace-mcp-server

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
  1. Only if you need to change account state (suspend/restore/create): in the same console create a Provisioning app, enable SCIM, and issue its Long-Lived Token into WORKS_SCIM_TOKEN. This is a second, separate credential β€” see Account state for why it is separate and why that is a feature.

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

worksmobile suspend alum@corp.com --yes         # block login (reversible, data kept)
worksmobile activate alum@corp.com --yes        # restore login
worksmobile member-create new@corp.com --family Kim --given Minji \
    --personal-email minji@gmail.com --yes      # personal mail required without SSO

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_scim_status

is the provisioning plane usable (separate token)

works_user_suspend / works_user_activate

⚠

block / restore login (reversible)

works_user_create

⚠

create a member (occupies a licensed seat)

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.

Account state: the SCIM plane

Suspending an account is not available on the credential the rest of this package uses. The Directory API exposes isSuspended as read-only, so for a long time "suspend the leaver" was a thing a human did in the console β€” which, on the tenant this was built against, meant it was never done: 0 of 136 accounts were suspended while ex-members kept live mail and drive.

The write lives on a different API family, reached with its own Long-Lived Token:

PATCH /scim/v2/Users/{id}   {"op": "replace", "path": "active", "value": false}

Keeping it on a separate credential is the safety property, not an inconvenience.

  • This token cannot permanently delete a member. Even SCIM's DELETE /Users/{id} only deactivates and preserves the data. The Directory user scope, by contrast, ships a real DELETE /users that erases someone outright β€” and that is the operation which, in the incident behind this repo's reconciliation warnings, cost a current employee their account. Granting user scope to get suspension would hand the automation an irreversible verb it has no business holding. Granting SCIM gives it exactly the reversible one it needs.

  • works_user_suspend re-reads active after the write and fails loudly if the value did not change. A 2xx is not proof; login state is not something to report as done on the strength of a status code.

  • It refuses *.serviceaccount@ addresses. Service accounts sit in the same member list as people, and suspending the one your own automation authenticates as takes the tooling down with it.

  • userName is resolved by lookup, never guessed: the SCIM path id is not documented to equal the Directory userId. Zero matches and two matches are reported differently β€” two accounts sharing a userName is an alarm, not an empty result.

Two more things the API does not make obvious:

  • Creating a member needs a personal email on domains without SSO. emails with type: other is where the password-registration mail goes, and such a member is created inactive until that registration completes. Omitting it there does not lose a field, it fails the creation β€” so --personal-email / personal_email exists and is worth asking the user for rather than guessing.

  • active is not a required response field and its default is true. So a re-read that simply does not mention it says nothing about login state, and coercing that silence with bool() would read it as "suspended" β€” the exact opposite of the default. get_active demands an explicit boolean and raises otherwise: a verification step that invents the answer it was built to check is worse than no verification.

Two traps worth stating plainly:

  • Leave of absence is a different axis from login. leaveOfAbsence is a console-only marker, not a SCIM attribute, and it does not block login. Treating "on leave" and "suspended" as one state leaves people marked absent who can still sign in β€” and tools that conflate them will report the job done without doing it. These verbs touch active only, and say so when the marker is left behind.

  • The token has a 90-day sliding expiry that any call renews. So a scheduled consumer that only calls SCIM when it has work to do will sit untouched for 90 days and then fail at the first real suspension. Call scim.keepalive() on every run, including the empty ones, and have doctor fail β€” not warn β€” when a configured token stops answering.

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).

  • Delegation to a suspended account fails. Every delegated read of that member β€” My Drive, received shares, their footprint β€” becomes unavailable the moment you suspend them. This is the hard version of "collect first, suspend second": it is not that the data is gone, it is that your credential can no longer reach it.

  • GET /users/me/drive returns a drive-only quota for the delegated member. There is no admin-side endpoint for it and no mail-volume endpoint at all β€” per-member mail usage is visible only in the admin console's statistics. Budget for a console trip.

  • Distinguish 403 from 404 before concluding an endpoint does not exist. Mail paths under /users/me/mail/* answer 403 has not permission api scope β€” they exist and the scope is missing. Invented paths (/users/me/mailboxes, /users/me/storage) answer 404 Api not exists. We recorded "there is no mail API" for a while on the strength of a 403, which was simply wrong.

  • A mail scope you have not registered in the console is rejected at token issue with invalid_scope, not at the endpoint β€” so a failing token request tells you about console configuration, not about your code.

  • Think twice before adding a mail scope to a delegatable app. The same key can act as any member, so mail-read on it is not "read mail" β€” it is "open every mailbox in the tenant". If you need it, put it on a separate app whose delegation target, retention and audit trail you have decided on first.

License

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
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers