worksmobile-mcp
Unofficial NAVER WORKS Drive admin MCP server for delegated service-account access to shared drives and members' My Drive.
List and inspect shared drives, including
accessibleRangeandpermissionType.List files/folders in shared drives or a delegated user's My Drive; download/upload files and create My Drive folders.
List, grant, and revoke individual drive/folder permissions; enable/disable folder permission inheritance.
Create/delete My Drive sharing shortcuts and list a member's received shares.
Search drive files, make raw authenticated WORKS API calls, and require
confirm=truefor mutating operations.
Provides admin tools for LINE WORKS Drive, including shared-drive governance, permission management, folder inheritance controls, share creation, file upload/download, and search via service-account delegation.
Provides admin tools for NAVER WORKS Drive, including shared-drive governance, permission management, folder inheritance controls, share creation, file upload/download, and search via service-account delegation.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@worksmobile-mcp show permissions for drive @2001000000xxxxxx"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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=trueparameter. 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
accessibleRangePATCH transitions wipe granted permissions; folderenablebreaks inheritance;disabledrops folder grants.
Related MCP server: google-workspace-mcp-server
Setup
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).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 valuesOnly 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 SSOAll 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 |
| shared drives & settings | |
| files of a shared drive or a member's My Drive | |
| drive/folder permissions | |
| β | grant / delete one permission |
| β | folder inheritance gate |
| storage-redirect download / 2-step upload | |
| My Drive folder | |
| β | "shared with me" shortcuts (My Drive only) |
| a member's received shares | |
| drive search | |
| tenant members (needs | |
| account-hygiene findings + dormant-check report | |
| reconcile accounts against an external roster | |
| one member's full reach β the offboarding query | |
| is the provisioning plane usable (separate token) | |
| β | block / restore login (reversible) |
| β | create a member (occupies a licensed seat) |
| β | 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'smasters[]. 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 Directoryuserscope, by contrast, ships a realDELETE /usersthat erases someone outright β and that is the operation which, in the incident behind this repo's reconciliation warnings, cost a current employee their account. Grantinguserscope 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_suspendre-readsactiveafter 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.userNameis resolved by lookup, never guessed: the SCIM path id is not documented to equal the DirectoryuserId. Zero matches and two matches are reported differently β two accounts sharing auserNameis 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.
emailswithtype: otheris 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_emailexists and is worth asking the user for rather than guessing.activeis not a required response field and its default istrue. So a re-read that simply does not mention it says nothing about login state, and coercing that silence withbool()would read it as "suspended" β the exact opposite of the default.get_activedemands 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.
leaveOfAbsenceis 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 touchactiveonly, 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 havedoctorfail β not warn β when a configured token stops answering.
API notes (hard-won)
accessibleRangeis 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 β
uploadUrlPUT); download is a 302 whose storage location also requires the Bearer token.GET /sharedrivesresponds{"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/drivereturns 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/*answer403 has not permission api scopeβ they exist and the scope is missing. Invented paths (/users/me/mailboxes,/users/me/storage) answer404 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 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.10035 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