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/

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: synology-office-mcp

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

⚠ = 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.

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