NAVER WORKS MCP

Hermes에서 자연어로 NAVER WORKS의 일정·연락처·구성원 정보를 조회하게 해 주는 MCP 서버입니다. 처음에는 안전한 읽기 전용으로 동작하며, MCP 프로토콜 2026-07-28의 무상태 HTTP 규칙과 로컬 stdio 연결을 함께 제공합니다.

처음 사용하는 분은 비개발자용 HTML 설명서를 먼저 여세요. 화면에서 순서대로 따라 하면 됩니다.

이 프로젝트가 하는 일

• Hermes가 MCP 도구를 호출하면 NAVER WORKS API에 읽기 요청을 보냅니다.

• 일정 속성, 일정 목록, 연락처 검색, 조직 구성원 목록/프로필을 제공합니다.

• 기본값은 로컬 컴퓨터에서만 실행되는 stdio입니다. 인터넷에 공개하지 않아 가장 안전합니다.

• 실제 토큰이 없을 때는 NAVER_WORKS_MOCK=true로 연결 연습과 계약 테스트를 할 수 있습니다.

• 메시지 보내기, 수정/삭제, Mail·Drive·Board·Task·Form 같은 기능은 현재 등록하지 않았습니다.

Related MCP server: Internal Data MCP Server

먼저 준비할 것

1. Windows/macOS/Linux 중 하나

2. Node.js 20.11 이상

3. NAVER WORKS Developer Console에서 발급한 사용자 OAuth Access Token

4. 조회할 NAVER WORKS 사용자의 userId

5. Hermes의 MCP 서버 추가 화면

OAuth 로그인·Refresh Token 갱신·Service Account JWT 서명은 이 저장소가 담당하지 않습니다. 외부 OAuth/Secret Provider에서 발급한 Bearer Access Token을 환경 변수로 넣는 구조입니다. 토큰은 GitHub, README, HTML 파일에 절대 적지 마세요.

지원 환경과 연결 방식

운영 환경을 자동으로 판단하지 말고, 설치 지시문이 먼저 운영체제·컨테이너 여부·Hermes의 터미널 실행 가능 여부를 확인하게 하세요. 개인 PC에서는 stdio가 가장 단순하고 안전합니다.

10분 안에 로컬 연결하기

1) 소스 받기

이미 이 폴더가 있다면 이 단계는 건너뛰세요.

Windows PowerShell:

git clone https://github.com/QriumJ/NAVER_WORKS_MCP.git NAVER_WORKS_MCP
Set-Location NAVER_WORKS_MCP

Ubuntu:

git clone https://github.com/QriumJ/NAVER_WORKS_MCP.git NAVER_WORKS_MCP
cd NAVER_WORKS_MCP

현재 완성본은 GitHub main에 병합되어 있습니다. 특정 개발 브랜치를 시험할 때만 --branch 브랜치명을 추가하세요.

2) 설치하고 설정 파일 만들기

Windows PowerShell:

npm install
Copy-Item .env.example .env

Ubuntu:

npm install
cp .env.example .env

.env를 메모장으로 열어 먼저 연습 모드로 확인합니다.

MCP_TRANSPORT=stdio
NAVER_WORKS_MOCK=true
NAVER_WORKS_USER_ID=mock-user

3) 빌드와 테스트

Windows PowerShell 또는 Ubuntu:

npm run build
npm test

22 passing이 나오면 프로그램 자체는 정상입니다.

4) Hermes에 서버 등록

Hermes의 MCP 서버 추가 화면에서 전송 방식은 stdio를 선택하고, 아래처럼 현재 운영체제의 절대 경로를 넣습니다. Hermes 버전에 따라 항목 이름이 command, args, env 또는 실행 파일, 인자, 환경 변수로 보일 수 있습니다.

Windows:

{
  "name": "naver-works",
  "command": "node",
  "args": ["C:\\Users\\Home\\Documents\\네이버웍스\\dist\\index.js"],
  "env": {
    "MCP_TRANSPORT": "stdio",
    "NAVER_WORKS_MOCK": "true",
    "NAVER_WORKS_USER_ID": "mock-user"
  }
}

Ubuntu:

{
  "name": "naver-works",
  "command": "node",
  "args": ["/home/your-user/NAVER_WORKS_MCP/dist/index.js"],
  "env": {
    "MCP_TRANSPORT": "stdio",
    "NAVER_WORKS_MOCK": "true",
    "NAVER_WORKS_USER_ID": "mock-user"
  }
}

args의 경로는 실제 폴더에 맞게 바꾸세요. Windows는 C:\...\\dist\index.js, Ubuntu는 /home/.../dist/index.js처럼 운영체제의 절대 경로를 사용합니다. Hermes에 cwd(작업 폴더) 항목이 있다면 이 프로젝트 폴더를 지정하면 .env도 자동으로 읽습니다.

5) Hermes에서 확인

서버를 저장하고 Hermes 채팅에서 다음처럼 말해 보세요.

NAVER WORKS에서 내 프로필을 조회해 줘.

연습 모드에서는 mock-user가 반환됩니다. 응답이 오면 Hermes ↔ MCP 연결은 끝난 것입니다.

Hermes 채팅으로 설치시키는 지시문

Hermes가 터미널과 파일을 실행할 수 있다면 아래 지시문 전체를 Hermes 채팅에 붙여 넣으세요. Hermes가 실행 권한을 지원하지 않는 경우에는 명령을 대신 보여 달라고 요청하고, 이 README의 명령을 직접 실행하면 됩니다.

내 환경을 먼저 확인한 뒤 NAVER WORKS MCP를 설치하고 Hermes에 연결해 줘.

규칙:
1. 운영체제가 Windows인지 Ubuntu/Linux인지, Hermes가 Docker 컨테이너 안에서 실행 중인지, 터미널·파일 실행 권한이 있는지 먼저 확인하고 결과를 알려 줘.
2. Node.js 20.11 이상, npm, Git이 설치되어 있는지 확인해. Docker라면 Docker 이미지에서 Node.js 22 이상을 사용해.
3. 기존 저장소가 있으면 파일을 삭제하지 말고 현재 변경사항과 브랜치를 먼저 확인해.
4. 저장소가 없으면 기본 `main`을 내려받아. Windows는 PowerShell 경로, Ubuntu는 bash 경로를 사용해:
   git clone https://github.com/QriumJ/NAVER_WORKS_MCP.git NAVER_WORKS_MCP
5. 저장소 폴더에서 npm install과 npm run build를 실행해. Docker라면 Dockerfile 또는 compose.yaml을 사용해.
6. 실제 토큰을 요구하거나 출력하지 말고, NAVER_WORKS_MOCK=true로 npm test를 실행해 22개 테스트 결과를 확인해.
7. Hermes와 MCP가 같은 환경이면 stdio를 사용해. 다른 Docker 컨테이너라면 MCP를 compose.yaml의 HTTP 서비스로 띄우고 Hermes에는 http://naver-works-mcp:8787/mcp를 설정해.
8. HTTP Docker 서비스는 MCP_HOST=0.0.0.0, 32자 이상 MCP_SHARED_SECRET, MCP_ALLOWED_HOSTS에 실제 서비스 이름을 설정하고 외부 공개 시 TLS reverse proxy를 사용해. 공유 시크릿을 채팅에 출력하지 마.
9. 설치·빌드·테스트·등록 결과를 단계별로 보고하고, 실패하면 원인과 다음 명령만 알려 줘.
10. NAVER_WORKS_ACCESS_TOKEN, 비밀번호, 개인정보를 채팅에 출력하거나 Git에 커밋하지 마.
11. 실제 NAVER WORKS 연결은 내가 별도로 OAuth 토큰을 준비했다고 말한 뒤에만 진행해. 그때도 토큰 값은 화면에 다시 출력하지 말고 환경 변수나 Secret Manager에만 저장해.
12. 쓰기·삭제·메시지 전송 기능은 추가하지 말고, 현재 읽기 전용 도구만 등록해.

Hermes가 “설치 완료”라고 답하면 채팅에서 NAVER WORKS에서 내 프로필을 조회해 줘라고 테스트하세요. 실제 데이터를 연결할 때만 NAVER_WORKS_MOCK=false와 외부 Token Provider가 발급한 Access Token을 설정합니다.

Docker에서 Hermes와 연결하기

A. Hermes와 MCP가 같은 Docker 컨테이너에 있을 때

이미지를 빌드한 뒤 stdio 프로세스로 실행합니다. MCP 프로토콜은 줄바꿈 기반이므로 -i를 사용하고 -t(가상 터미널)는 붙이지 않습니다.

Windows PowerShell:

docker build -t naver-works-mcp:local .
docker run --rm -i --env-file .env naver-works-mcp:local node dist/index.js

Ubuntu:

docker build -t naver-works-mcp:local .
docker run --rm -i --env-file .env naver-works-mcp:local node dist/index.js

Hermes가 Docker 밖에 있고 Docker MCP를 자식 프로세스로 실행할 수 있으면 Hermes의 stdio 설정을 command=docker로, 인자를 run --rm -i --env-file <절대경로>/.env naver-works-mcp:local node dist/index.js로 지정합니다.

B. Hermes와 MCP가 서로 다른 Docker 컨테이너일 때

이 저장소의 compose.yaml은 MCP를 HTTP 서비스로 띄우고, 호스트에는 loopback으로만 포트를 공개합니다. 먼저 .env에 32자 이상의 MCP_SHARED_SECRET을 직접 생성해 넣으세요.

Windows PowerShell:

Copy-Item .env.example .env
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
docker compose up --build

Ubuntu:

cp .env.example .env
openssl rand -hex 32
docker compose up --build

출력한 랜덤 문자열은 .env의 MCP_SHARED_SECRET 값으로만 저장합니다. 다른 컨테이너의 Hermes는 서비스 이름을 사용해 http://naver-works-mcp:8787/mcp에 연결하고, X-MCP-Shared-Secret 헤더를 보냅니다. Hermes가 MCP 2026-07-28 HTTP envelope를 지원하지 않으면 B 방식 대신 A 방식(stdio)을 사용하세요.

실제 NAVER WORKS API 연결

1) Developer Console에서 확인

앱의 사용자 OAuth 권한에 다음 읽기 Scope를 요청합니다.

calendar.read
contact.read
directory.read
user.profile.read

조직 정책에 따라 관리자 승인과 Redirect URL 등록이 필요할 수 있습니다. 실제 토큰은 OAuth 로그인 후 외부 Token Provider에서 발급받으세요.

2) .env에 실제 값 입력

MCP_TRANSPORT=stdio
NAVER_WORKS_MOCK=false
NAVER_WORKS_ACCESS_TOKEN=여기에_짧은_수명의_Bearer_토큰
NAVER_WORKS_USER_ID=조회할_사용자_ID
NAVER_WORKS_AUTH_MODE=user_oauth
NAVER_WORKS_API_BASE=https://www.worksapis.com/v1.0
NAVER_WORKS_ENFORCE_SCOPES=true
NAVER_WORKS_SCOPES=calendar.read,contact.read,directory.read,user.profile.read

토큰 앞에 Bearer 를 붙이지 마세요. 서버가 요청 헤더에 자동으로 붙입니다. 토큰을 바꾼 뒤 Hermes를 완전히 다시 시작해야 새 환경 변수가 반영됩니다.

HTTP로 연결하고 싶은 경우(고급)

대부분의 개인 사용자는 stdio를 권장합니다. 다른 컴퓨터나 원격 Hermes가 연결해야 할 때만 HTTP를 사용하세요.

Windows PowerShell:

npm run build
$env:MCP_TRANSPORT="http"
$env:MCP_HOST="127.0.0.1"
$env:MCP_PORT="8787"
node dist/index.js

Ubuntu:

npm run build
MCP_TRANSPORT=http MCP_HOST=127.0.0.1 MCP_PORT=8787 node dist/index.js

정상 실행 후 http://127.0.0.1:8787/healthz에서 상태를 확인할 수 있습니다. HTTP /mcp는 MCP 2026-07-28 strict stateless envelope와 표준 헤더를 요구합니다. 원격 바인딩은 32자 이상의 MCP_SHARED_SECRET, 허용 Host 목록, TLS reverse proxy가 모두 필요합니다. 공유 시크릿 없이 인터넷에 공개하지 마세요.

제공되는 도구

PII는 필요한 최소 필드만 반환하고, 쓰기·삭제 도구는 의도적으로 없습니다.

자주 생기는 문제

검수 및 문서

npm run build
npm test
npm audit --omit=dev

현재 검수 결과는 98/100, P0/P1 결함 없음입니다. 남은 항목은 포트 문자열의 더 엄격한 파싱, 실테넌트 권한 검증, 실제 Hermes 클라이언트의 2026-07-28 지원 확인 같은 운영 단계입니다.

• 비개발자용 Hermes·NAVER WORKS 연결 설명서

• Docker 이미지 · Docker Compose 구성

• MCP 2026-07-28 기획·검수 기록

• NAVER WORKS API 공식 문서

• MCP 2026-07-28 설명

• MCP 2025-11-25 배경