nworks

NAVER WORKS CLI + MCP server. 26 tools for messages, calendar, drive, mail, tasks, and boards.

GitHub

nworks

npm version license npm downloads

First full MCP server for NAVER WORKS. NAVER WORKS API를 스크립트나 AI 에이전트에서 쓰기 쉽게 만든 CLI + MCP 서버입니다.

Automate messages, calendar, drive, mail, tasks, and boards — from CLI or AI agents.

Quickstart

npm install -g nworks
nworks login --user
nworks calendar list

AI 에이전트가 실제로 이렇게 씁니다

User: 오늘 일정 알려줘

Claude → nworks_calendar_list
  → 3건: 스탠드업(10:00), 점심미팅(12:00), 코드리뷰(15:00)

User: 팀 채널에 배포 완료 메시지 보내줘

Claude → nworks_message_send
  { "channel": "C001", "text": "v1.2.0 배포 완료" }
  → 메시지가 전송되었습니다

Install

npx nworks          # 바로 실행
npm install -g nworks  # 글로벌 설치

로그인

# User OAuth (캘린더, 드라이브, 메일, 할 일, 게시판)
nworks login --user --scope "calendar,calendar.read,file,file.read,mail,mail.read,task,task.read,board,board.read,user.read"

# 봇 메시지 전송이 필요한 경우 (Service Account)
nworks login

# 인증 확인
nworks whoami

# 로그아웃
nworks logout

nworks login --user는 CLIENT_ID + CLIENT_SECRET만 있으면 됩니다. 환경변수나 기존 설정에 이미 있는 값은 다시 물어보지 않습니다.

Developer Console 설정: User OAuth를 사용하려면 Developer Console에서 Redirect URL에 http://localhost:9876/callback을 등록해야 합니다.

MCP 서버 (AI 에이전트 연동)

Claude Desktop, Cursor 등에서 MCP server로 NAVER WORKS 26개 도구를 사용할 수 있습니다. 메시지 전송, 일정 관리, 파일 업로드, 메일, 할 일, 게시판까지 — AI 에이전트가 NAVER WORKS 워크플로우를 자동화합니다.

설정

먼저 로그인합니다:

nworks login --user --scope "calendar,calendar.read,file,file.read,mail,mail.read,task,task.read,board,board.read,user.read"

그리고 MCP 설정에 추가합니다 (~/.config/claude/claude_desktop_config.json):

{
  "mcpServers": {
    "nworks": {
      "command": "nworks",
      "args": ["mcp"]
    }
  }
}

끝입니다. 인증 한 번으로 26개 도구 모두 사용 가능 — 별도 env 설정이 필요 없습니다.

MCP에서 AI 에이전트가 직접 설정하기: CLI 로그인 없이도 AI 에이전트가 nworks_setup → nworks_login_user 순서로 호출하면 브라우저 로그인만으로 전체 기능을 사용할 수 있습니다.

MCP 도구 목록 (26개)

도구설명필요 인증
설정/인증
nworks_setupAPI 인증 정보 설정 (Client ID/Secret 등)—
nworks_login_userUser OAuth 브라우저 로그인 (전체 scope 자동 포함)—
nworks_logout인증 정보 및 토큰 삭제—
nworks_whoami인증 상태 확인—
nworks_doctor연결 상태 진단 (인증, 토큰, API 점검)—
메시지
nworks_message_send사용자/채널에 메시지 전송Service Account
nworks_message_members채널 구성원 조회Service Account
nworks_directory_members조직 구성원 조회Service Account
캘린더
nworks_calendar_list캘린더 일정 조회User OAuth (calendar.read)
nworks_calendar_create캘린더 일정 생성User OAuth (calendar + calendar.read)
nworks_calendar_update캘린더 일정 수정User OAuth (calendar + calendar.read)
nworks_calendar_delete캘린더 일정 삭제User OAuth (calendar + calendar.read)
드라이브
nworks_drive_list드라이브 파일/폴더 목록User OAuth (file.read)
nworks_drive_upload드라이브 파일 업로드User OAuth (file)
nworks_drive_download드라이브 파일 다운로드 (5MB 초과 시 로컬 저장)User OAuth (file.read)
메일
nworks_mail_send메일 전송User OAuth (mail)
nworks_mail_list메일 목록 조회User OAuth (mail.read)
nworks_mail_read메일 상세 조회User OAuth (mail.read)
할 일
nworks_task_list할 일 목록 조회User OAuth (task.read)
nworks_task_create할 일 생성User OAuth (task + user.read)
nworks_task_update할 일 수정/완료User OAuth (task + user.read)
nworks_task_delete할 일 삭제User OAuth (task + user.read)
게시판
nworks_board_list게시판 목록 조회User OAuth (board.read)
nworks_board_posts게시판 글 목록 조회User OAuth (board.read)
nworks_board_read게시판 글 상세 조회User OAuth (board.read)
nworks_board_create게시판 글 작성User OAuth (board)

AI 에이전트 사용 예시

User: 내일 오후 2시에 회의 잡고, 팀 채널에 알려줘

Claude → nworks_calendar_create
  { "summary": "회의", "start": "2026-03-15T14:00:00", "end": "2026-03-15T15:00:00" }
  → 일정이 생성되었습니다

Claude → nworks_message_send
  { "channel": "C001", "text": "내일 14:00 회의가 잡혔습니다" }
  → 메시지가 전송되었습니다

CLI 사용법

모든 명령어에 --json 지원 (파이프, 스크립트, 에이전트 파싱 용이). message send, mail send, drive upload는 --dry-run으로 실제 전송 없이 테스트 가능.

메시지 (Bot API)

# 사용자에게 텍스트 메시지
nworks message send --to <userId> --text "메시지"

# 채널에 텍스트 메시지
nworks message send --channel <channelId> --text "메시지"

# 버튼 메시지
nworks message send --to <userId> --type button --text "PR 리뷰 요청" \
  --actions '[{"type":"message","label":"승인","postback":"approve"}]'

# 리스트 메시지
nworks message send --to <userId> --type list --text "오늘의 할 일" \
  --elements '[{"title":"코드 리뷰","subtitle":"#382 PR"}]'

# 채널 구성원 조회
nworks message members --channel <channelId>

조직 (Directory API)

nworks directory members   # 조직 구성원 목록

캘린더 (User OAuth)

# 오늘 일정 조회
nworks calendar list

# 기간 지정
nworks calendar list --from "2026-03-14T00:00:00+09:00" --until "2026-03-14T23:59:59+09:00"

# 일정 생성
nworks calendar create --title "회의" --start "2026-03-14T14:00+09:00" --end "2026-03-14T15:00+09:00"

# 장소/설명 포함
nworks calendar create --title "점심 미팅" --start "2026-03-14T12:00+09:00" --end "2026-03-14T13:00+09:00" \
  --location "강남 식당" --description "분기 리뷰"

# 참석자 지정 + 알림
nworks calendar create --title "팀 회의" --start "2026-03-14T10:00+09:00" --end "2026-03-14T11:00+09:00" \
  --attendees "[email protected],[email protected]" --notify

# 일정 수정
nworks calendar update --id <eventId> --title "변경된 제목"

# 일정 삭제
nworks calendar delete --id <eventId>

드라이브 (User OAuth)

# 파일/폴더 목록
nworks drive list

# 파일 업로드
nworks drive upload --file ./report.pdf

# 특정 폴더에 업로드
nworks drive upload --file ./report.pdf --folder <folderId>

# 파일 다운로드
nworks drive download --file-id <fileId>

# 다운로드 경로/파일명 지정
nworks drive download --file-id <fileId> --out ./downloads --name report.pdf

메일 (User OAuth)

# 메일 전송
nworks mail send --to "[email protected]" --subject "제목" --body "내용"

# CC/BCC 포함
nworks mail send --to "[email protected]" --cc "[email protected]" --subject "제목" --body "내용"

# 받은편지함 목록
nworks mail list

# 읽지 않은 메일만
nworks mail list --unread

# 메일 상세 조회
nworks mail read --id <mailId>

할 일 (User OAuth)

# 할 일 목록
nworks task list

# 미완료만 조회
nworks task list --status TODO

# 할 일 생성
nworks task create --title "코드 리뷰" --body "PR #382 리뷰"

# 마감일 지정
nworks task create --title "배포" --due 2026-03-20

# 할 일 완료 처리
nworks task update --id <taskId> --status done

# 할 일 삭제
nworks task delete --id <taskId>

게시판 (User OAuth)

# 게시판 목록
nworks board list

# 게시판 글 목록
nworks board posts --board <boardId>

# 글 상세 조회
nworks board read --board <boardId> --post <postId>

# 글 작성
nworks board create --board <boardId> --title "공지사항" --body "내용"

# 알림 발송 + 댓글 비활성화
nworks board create --board <boardId> --title "공지" --body "내용" --notify --no-comment

OAuth Scope 설정

NAVER WORKS Developer Console에서 앱의 OAuth Scope를 추가해야 합니다.

Scope용도인증 방식필요한 명령어
botBot 메시지 전송Service Accountmessage send
bot.readBot 채널/구성원 조회Service Accountmessage members
calendar캘린더 쓰기User OAuthcalendar create/update/delete (calendar.read도 함께 필요)
calendar.read캘린더 읽기User OAuthcalendar list, calendar create/update/delete의 의존성
file드라이브 읽기/쓰기User OAuthdrive list/upload/download
file.read드라이브 읽기 전용User OAuthdrive list/download
mail메일 읽기/쓰기User OAuthmail send/list/read
mail.read메일 읽기 전용User OAuthmail list/read
task할 일 읽기/쓰기User OAuthtask create/update/delete (user.read도 함께 필요)
task.read할 일 읽기 전용User OAuthtask list
user.read사용자 정보 조회Service Account / User OAuthdirectory members, task create/update/delete의 의존성
board게시판 읽기/쓰기User OAuthboard list/posts/read/create
board.read게시판 읽기 전용User OAuthboard list/posts/read

Tip: scope를 변경한 후에는 토큰을 재발급해야 합니다.

nworks logout && nworks login --user --scope "..."

사용 시나리오

CI/CD 배포 알림

# GitHub Actions에서 배포 완료 후 팀 채널에 알림
nworks message send --channel $CHANNEL_ID --text "v${VERSION} 배포 완료"

팀 자동화 스크립트

# 매일 아침 팀원에게 리마인더 전송
for userId in $(nworks directory members --json | jq -r '.users[].userId'); do
  nworks message send --to "$userId" --text "오늘의 스탠드업 10시입니다"
done

Advanced Configuration

환경 변수

환경변수로 인증 정보를 설정하면 nworks login 없이 바로 사용할 수 있습니다.

# 공통 (필수)
NWORKS_CLIENT_ID=          # 필수
NWORKS_CLIENT_SECRET=      # 필수

# 봇 메시지 전송 시에만 필요 (User OAuth만 쓰면 불필요)
NWORKS_SERVICE_ACCOUNT=    # 봇 전용
NWORKS_PRIVATE_KEY_PATH=   # 봇 전용
NWORKS_BOT_ID=             # 봇 전용

# 선택
NWORKS_DOMAIN_ID=          # optional
NWORKS_SCOPE=              # optional (기본: bot bot.read user.read)
NWORKS_VERBOSE=1           # optional, 디버그 로깅

MCP 서버에 환경 변수 직접 설정

nworks login 대신 환경 변수로 직접 설정할 수도 있습니다:

{
  "mcpServers": {
    "nworks": {
      "command": "npx",
      "args": ["-y", "nworks", "mcp"],
      "env": {
        "NWORKS_CLIENT_ID": "<Client ID>",
        "NWORKS_CLIENT_SECRET": "<Client Secret>"
      }
    }
  }
}

봇 메시지도 사용하려면 NWORKS_SERVICE_ACCOUNT, NWORKS_PRIVATE_KEY_PATH, NWORKS_BOT_ID도 추가합니다.

Roadmap

  • v0.1 — 메시지, 조직 구성원, MCP 서버
  • v0.2 — 캘린더 일정 조회 + User OAuth
  • v0.3 — 드라이브 파일 조회/업로드/다운로드
  • v0.4 — 메일 (mail send/list/read)
  • v0.5 — 할 일 (task list/create/update/delete)
  • v0.6 — 캘린더 쓰기 (calendar create/update/delete)
  • v0.7 — 게시판 (board list/posts/read/create)
  • v1.0 — User OAuth 단독 로그인, MCP/CLI 인증 UX 개선, AI 에이전트 전용 설정 flow (nworks_setup → nworks_login_user), scope 자동 확장, 한국어 에러 안내, nworks doctor

License

Apache-2.0

Related Servers