_[English](./README.en.md)_
# 데이터랩툴즈 커넥터
Claude 같은 AI 앱을 데이터랩툴즈에 연결해 주는 작은 무료 프로그램이에요. 연결되면 AI에게 이렇게 물어볼 수 있어요.
> "지난주 내 블로그 어땠어?"
그러면 짐작이 아니라 내 네이버 블로그·키워드·광고의 **실제 수치**로 답해요. **조회는 바로 되고, 고치는 건 물어봐요** — 글쓰기 창이나 편집기를 고치려면 따로 허용해야 하고, 발행은 하지 않아요. 처음이어도 보통 10분이면 끝나요.
## 준비물
컴퓨터마다 한 번씩만 준비하면 돼요.
| 준비물 | 어떻게 |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Chrome + 데이터랩툴즈 확장 | 아직 없다면 [app.datalab.tools](https://app.datalab.tools/)에서 설치해요. |
| AI 앱 | 질문을 받을 프로그램이에요. **컴퓨터에 설치하는 앱**만 돼요(웹사이트는 안 돼요). Claude Desktop은 [claude.ai](https://claude.ai/download)에서 무료로, ChatGPT는 **데스크톱 앱만** 되고 [openai.com](https://openai.com/)에서 받아요. |
| Node.js | 연결 프로그램을 실행하는 무료 프로그램이에요. [nodejs.org](https://nodejs.org/)의 **LTS** 버튼으로 받아요. 번거로우면 아래 [2단계](#2단계--설치)의 한 줄 설치가 Node.js까지 한 번에 깔아 줘요(관리자 권한도 필요 없어요). |
> 회사 컴퓨터는 보안 정책 때문에 설치가 막혀 있을 수 있어요. 시작 전에 회사 IT 담당자와 먼저 상의하면 시간을 아낄 수 있어요.
## 네 단계예요
| 단계 | 하는 일 | 어디서 |
| ----------- | ------------------------------------- | --------- |
| **1. 켜기** | 스위치를 켜고 **연결 키**를 복사해요 | 확장 설정 |
| **2. 설치** | 명령 한 줄을 실행하고 키를 붙여넣어요 | 터미널 |
| **3. 연결** | 사이드 패널을 열어요 | 확장 |
| **4. 확인** | AI 앱에서 시험 질문을 해 봐요 | AI 앱 |
1·2단계는 같은 화면에서 이어집니다. 설정 화면이 지금 어디까지 됐는지 알려 주니, 화면을 열어 둔 채로 따라오시면 돼요.
시작 전에 안심하고 싶다면 아래 [안전](#안전)을 먼저 읽으셔도 좋아요.
## 1단계 — 켜기
1. Chrome 오른쪽 위의 데이터랩툴즈 아이콘을 눌러 **사이드 패널**을 열어요. (안 보이면 퍼즐 조각 아이콘에서 찾을 수 있어요.)
2. 패널 아래쪽 **설정**을 눌러 **확장 설정** 화면을 열어요.
3. **"다른 AI 앱에 연결 (MCP)"** 스위치를 켜요. 동의 화면이 나오면 내용을 읽고 동의해요.
> "연결된 AI 앱이 요청하면 네이버 데이터가 해당 앱과 그 AI 제공사 서버로 전달돼요."
4. 아래에 **1 · 2 · 3 번호가 붙은 안내**가 펼쳐져요. **1번 [연결 키]** 칸의 **[복사]** 버튼을 누르세요(눈으로 확인하고 싶으면 [보기]).
> "이 값은 이 컴퓨터 전용 비밀번호예요. 다른 사람에게 보내지 마세요."
캡처 공유·채팅 전송은 피해 주세요. 이 키 하나가 AI 앱 설정에도, 이 컴퓨터의 다른 브라우저에도 그대로 쓰입니다.
## 2단계 — 설치
명령 한 줄이면 컴퓨터에 있는 AI 앱을 **모두 자동으로** 찾아 연결해 줘요. 앱마다 따로 할 일은 없어요.
1. **터미널을 열어요** — Windows는 검색창에 `cmd` → "명령 프롬프트", Mac은 `⌘+스페이스`로 `터미널`, Linux는 터미널 앱(보통 `Ctrl+Alt+T`)이에요.
2. **아래 명령을 붙여넣고 Enter를 눌러요.** 저장되는 명령은 정확한 시작 버전을 적습니다. 연결 프로그램은 시작할 때와 유휴 상태에서 정본 릴리스를 확인해 현재의 안전하고 호환되는 버전으로 승격합니다. 진단 환경에서는 `--no-self-update`로 승격을 끌 수 있어요.
```
npx -y @modootoday/datalab-extension-mcp@1.11.1 install
```
영어 글자가 여러 줄 올라오는 건 정상이에요. 이 명령은 연결 프로그램을 다운로드해 실행할 뿐, 다른 건 건드리지 않아요.
도우미는 네 대목으로 진행돼요 — `[1/4] 연결 키 확인`, `[2/4] 연결할 AI 프로그램 찾기`, `[3/4] 연결하는 중`, `[4/4] 결과`.
3. **연결 키를 붙여넣어요.** 도우미가 이렇게 물어봐요.
> "복사한 연결 키를 붙여넣어 주세요:"
1단계에서 복사한 값을 붙여넣고 Enter를 눌러요. 형식이 어긋나면 한 번 더 물어봐요.
4. **연결할지 확인해요.** 딱 하나만 물어봐요.
> "위 N개 프로그램에 연결할까요?" (엔터 = 예 / n = 아니오)
엔터를 누르면 앱별 결과와 함께 `N개 프로그램에 연결했어요.` 가 나와요. 찾은 앱이 0개면 AI 앱을 먼저 설치한 뒤 같은 명령을 다시 실행하면 돼요.
5. 마지막에 이 안내가 보이면 성공이에요.
> 마지막 한 단계: AI 앱을 완전히 종료했다가 다시 실행해 주세요.
> (Windows: 작업 표시줄 트레이 아이콘에서 종료)
창만 닫으면 뒤에서 계속 돌 수 있어요. **완전히 종료** 후 다시 켜세요 — Windows는 트레이 아이콘에서 종료, Mac은 `⌘+Q`, Linux는 앱 메뉴의 Quit.
Node.js가 없다면 — 한 줄로 한 번에 설치
위 명령이 `'npx'을(를) 찾을 수 없습니다` 오류를 내면 Node.js가 없는 거예요. 아래 명령 하나면 Node.js까지 설치(관리자 권한 없이)한 뒤 연결까지 이어 줘요. 이미 있으면 설치는 건너뛰어요. 이 방법을 [준비물](#준비물)의 Node.js 설치 대신 바로 써도 돼요.
- **Windows** (PowerShell을 열고 붙여넣어요):
```
irm https://app.datalab.tools/install/mcp.ps1 | iex
```
- **Mac · Linux** (터미널을 열고 붙여넣어요):
```
curl -fsSL https://app.datalab.tools/install/mcp.sh | sh
```
중간에 연결 키를 물어보면 1단계에서 복사한 값을 붙여넣어요. 아직 AI 앱이 하나도 없으면, 원하는 AI 프로그램을 그 자리에서 골라 설치할 수도 있어요(고르는 건 자유예요).
> 실행 전에 내용을 확인하고 싶으면 위 주소를 브라우저에 그대로 열어 보세요 — 받아서 실행할 스크립트 원문이 그대로 보여요.
**자동으로 연결되는 앱**: Claude Desktop, Claude Code, ChatGPT 데스크톱, Codex CLI, Gemini CLI, Cursor, Windsurf, Amazon Q Developer, JetBrains Junie, Kiro.
**안내문만 보여 주는 앱**(화면 안내를 따라 하면 돼요): VS Code, Zed, Cline, Roo Code, LM Studio, Warp.
## 3단계 — 연결
설치를 이 브라우저에서 하셨다면 할 일이 없어요. **사이드 패널을 열면** 이 브라우저가
자기 키로 붙습니다.
이 컴퓨터의 **다른 브라우저에서 이미 설치**했다면, 그 브라우저의 1번 **연결 키** 를 복사해
이 브라우저 1번 아래의 **[이 컴퓨터의 다른 브라우저에서 이미 설치했어요]** 에 넣으세요
(아래 [이 컴퓨터에 브라우저 하나 더 올리기](#이-컴퓨터에-브라우저-하나-더-올리기)).
실제 연결은 사이드 패널을 열어 둔 동안 이루어져요.
## 4단계 — 확인
- 사이드 패널 위쪽 카드가 **초록색**이고 "연결됨"이 보이면 된 거예요. 초록색이 아니면 [문제해결](#문제해결)로 가세요.
- AI 앱에서 "지난주 내 블로그 어땠어?" 처럼 물어보고 실제 수치가 나오면 전부 끝이에요.
## 알아 두면 좋은 것
- **패널이 열려 있는 동안에만 연결돼요.** 데이터랩툴즈 사이드 패널을 닫으면 연결도 함께 끊겨요. 다시 열면 자동으로 이어져요.
- 연결 프로그램은 다리일 뿐이에요 — 아이디·비밀번호를 저장하지 않고, 내 컴퓨터 밖에서는 동작하지 않아요.
- 화면 기능만 바뀐 업데이트는 강력 새로고침으로 적용됩니다. MCP 도구·스킬이 바뀐 버전은
확장 카드의 업데이트 안내에 따라 연결 프로그램을 다시 설치해야 해요.
## 설치된 작업 도움말 고르기
설치할 때 **작업 도움말(스킬)** 도 함께 놓입니다. 대화형 설치에서는 추천 9개를 먼저
보여 주고, 블로그 진단·플레이스 평판·품앗이·사진/영상 제작·자동 도구 탐색 같은 추가
도움말을 번호로 여러 개 고를 수 있어요. Enter를 누르면 추천 구성만 설치됩니다.
```
npx -y @modootoday/datalab-extension-mcp@1.11.1 skills list
npx -y @modootoday/datalab-extension-mcp@1.11.1 skills status
npx -y @modootoday/datalab-extension-mcp@1.11.1 skills attach <이름>
npx -y @modootoday/datalab-extension-mcp@1.11.1 skills detach <이름>
```
- `list` 는 이 버전에 들어 있는 전부를 이름과 설명으로 보여 줘요.
- `status` 는 지금 내 컴퓨터의 어느 폴더에 무엇이 들어가 있는지 보여 줘요.
- `attach` / `detach` 로 하나씩 넣고 뺍니다.
- 자동 설치에서는 `--skill <이름>`을 반복해 추가하거나 `--all-skills`로 전부, `--no-skills`로
도움말 없이 설치할 수 있어요.
AI 사진 생성 전용 도움말은 확장 패널에만 표시됩니다. MCP에서 실제로 사용할 수 없는 도구를
가르치지 않기 위한 구분입니다.
다른 도구로 설치한 같은 이름의 도움말이 있으면 **건드리지 않고 그렇게 말해요.** 뺄 때도 우리가 넣은 파일만 지웁니다.
## 이 컴퓨터에 브라우저 하나 더 올리기
연결 키는 **이 컴퓨터에 하나**예요. 브라우저를 더 올리시려면 이미 연결된 브라우저의
확장 설정 → **다른 AI 앱에 연결 (MCP)** → 1번 **연결 키** 의 `복사` 를 누르고, 올릴
브라우저의 같은 화면에서 **[이 컴퓨터의 다른 브라우저에서 이미 설치했어요]** 를 펼쳐
붙여넣으시면 됩니다. 등록 코드도, 발급도, 목록도 없어요.
**한 컴퓨터 안에서만** 됩니다 — 연결 프로그램은 127.0.0.1 에서만 듣기 때문에 다른
컴퓨터는 닿지 못하고, 키는 남에게 보낼 것이 아니에요.
AI 앱이 지금 어떤 브라우저에 닿는지는 `datalab_browsers` 로 물어보시면 돼요. 붙어 있는
브라우저만 답하고, 이름은 각 브라우저가 스스로 알려 준 것입니다.
## 문제해결
무슨 일이든 첫 질문은 하나예요 — **패널이 열려 있나요?** 카드 상태가 "문제 발생"이면 그 아래 빨간 문장을 아래 소제목에서 찾아보세요. 여기 없는 문장이 떴다면 연결 프로그램이 그대로 전해 준 오류예요 — 아래 "위 어느 것도 아닐 때" 의 기록 파일을 보시면 돼요.
### "연결을 기다리고 있어요. AI 앱을 켜면 자동으로 연결돼요."
오류가 아니라 정상이에요. AI 앱을 실행하면 자동으로 연결돼요.
### "네이버 페이지를 열면 연결돼요. MCP 는 네이버 탭이 열려 있는 동안에만 동작해요."
MCP 를 켜 두었지만 **네이버 페이지가 한 곳도 열려 있지 않을 때** 나와요. 이 상태에서는
연결 프로그램 자체가 시작되지 않기 때문에, AI 앱을 켜도 연결되지 않아요. 네이버 블로그나
스마트플레이스 같은 페이지를 한 탭 열어 두면 자동으로 연결돼요.
### "연결 프로그램이 예전 버전이에요. 새 설정을 AI 앱 설정에 붙여넣고…"
카드의 **[새 설정 복사]** 버튼을 누르고 안내대로 붙여넣은 뒤, AI 앱을 완전히 껐다가 다시 켜요.
### "연결 프로그램이 이 브라우저의 키를 받지 않아요…"
원인은 둘 중 하나이고, 연결 프로그램은 어느 쪽인지 알려 주지 않아요.
**이 컴퓨터의 다른 브라우저에서 설치했다면** — 그 브라우저의 연결 키를 이 브라우저에
넣으면 끝이에요([이 컴퓨터에 브라우저 하나 더 올리기](#이-컴퓨터에-브라우저-하나-더-올리기)).
여기서 새 설정을 붙여넣으면 **그 브라우저가 끊깁니다.**
**그런 적이 없다면** AI 앱이 켜질 때 받은 옛 키로 연결 프로그램이 돌고 있는 거예요.
**[다시 연결하기]는 도움이 안 돼요** — 상대가 계속 같은 옛 키를 내밀거든요.
1. 카드의 **[새 설정 복사]** 를 누르고
2. 그 내용을 AI 앱 설정에 붙여넣은 뒤
3. **그 AI 앱을 완전히 종료했다가 다시 켜요** (창 닫기 말고 — Windows 트레이 종료 / Mac `⌘+Q` / Linux 앱 메뉴 Quit)
3번까지 해야 연결 프로그램이 AI 앱 설정에 저장된 연결 키로 다시 떠요.
### "연결 통로(포트)를 다른 프로그램이 쓰고 있어요."
카드의 **[업데이트 명령어 복사]** 버튼을 눌러 터미널에 붙여넣어 실행하면 연결 프로그램이 새 설정으로 다시 연결돼요.
### "크롬에서 데이터랩툴즈 패널이 닫혀 있어요. 크롬을 열고 데이터랩툴즈 패널을 열어 두면 바로 동작해요."
말 그대로예요. Chrome을 열고 데이터랩툴즈 사이드 패널을 열어 두면 바로 동작해요.
### 도구가 10개밖에 안 보여요
정상이에요. **일부러 그렇게 보냅니다.**
전체 도구는 211개인데, 그걸 전부 목록으로 보내면 AI 앱마다 정해 둔 상한에 걸려요.
어떤 앱은 넘치는 만큼 조용히 잘라내고, 어떤 앱은 아예 연결을 거부해요. 그래서 자주 쓰는
탐색 도구만 목록에 올리고, 나머지는 **AI가 요청 의도를 찾아 답으로 건네받습니다.**
"우리 매장 리뷰 좀 보여줘"처럼 목록에 없는 일을 부탁하면 AI가 사용자 표현을 탐색 도구에
보내 후보와 인자 형식을 받은 뒤 실행합니다. 조사 변화·띄어쓰기·가벼운 오타도 로컬 유사도
검색으로 보완합니다. 바로 찾지 못하면 기능 묶음을 먼저 보여주고, 고른 묶음의 도구를 기본
8개씩 나눠 확인합니다. 처음 부르는 도구는 이 조회 때문에 답이 1~2초 늦을 수 있어요.
AI가 "그런 기능은 없다" 고 답하면, **"숨은 도구를 찾아보고 다시 답해줘"** 라고 한 번
말해 주세요.
### 카드는 초록색인데 AI 앱이 도구를 못 찾을 때
가장 흔한 경우예요. **AI 앱을 완전히 껐다가 다시 켜지 않아서** 그래요 — 창만 닫으면 뒤에서 계속 돌고, 그 상태로는 새로 연결된 도구를 못 봐요.
- **Windows** — 작업 표시줄 오른쪽 아래 트레이 아이콘에서 종료
- **Mac** — `⌘+Q` (창 닫기가 아니라 종료)
- **Linux** — 앱 메뉴의 Quit, 또는 터미널에서 프로세스 종료
완전히 종료한 뒤 다시 켜면 도구 목록을 새로 읽어요. 그래도 안 보이면 2단계 명령을 한 번 더 실행해 주세요.
연결이 어느 날 사라졌어요 / 'npx'를 찾을 수 없대요
- **연결이 사라졌을 때** — 처음 실행했던 그 명령을 한 번 더 실행하면 안전하게 다시 등록돼요. (일부 AI 앱이 설정 파일을 정리하며 연결을 지우기도 해요.)
```
npx -y @modootoday/datalab-extension-mcp@1.11.1 install
```
- **`'npx'을(는) 내부 또는 외부 명령...`** — Node.js가 없는 거예요. 위 2단계의 "Node.js가 없다면" 한 줄 설치가 가장 간단해요.
- **위 어느 것도 아닐 때** — 연결 프로그램이 무슨 일을 겪었는지 기록해 둬요. 파일 하나만 열어 보면 돼요.
```
~/.datalab-mcp/connector.log
```
마지막 줄들이 그때 무슨 일이 있었는지 알려 줘요. 너무 커지지 않게 일정 크기가 넘으면 자동으로 넘겨서, 파일은 최대 두 개까지만 생겨요. 도움을 요청할 때 이 파일의 마지막 부분을 같이 보내 주시면 훨씬 빨라요. (조회한 내용이나 글 내용은 들어가지 않아요.)
## 안전
- **조회는 그냥 되고, 고치는 건 그때그때 허락받아요.** 데이터 조회는 바로 돼요. **네이버 글쓰기 창**과 사진·영상 편집기의 내용을 고치는 것 — 제목·본문 넣기, 되돌리기, 본문을 통째로 바꾸기, 사진 넣기, 편집기 창 닫기, 지우기 — 은 실행 전에 **할 때마다** 사이드패널에서 물어봐요. 요금이 드는 기능도 같습니다. **미리 켜 두는 설정은 없어요.** 글 발행과 광고비 집행은 어떤 경우에도 열리지 않아요.
- **발행은 하지 않아요.** 글을 올리거나 공개하는 기능은 연결되지 않습니다 — 고친 내용은 글쓰기 창에 남고, 올릴지는 사용자가 직접 정해요.
- **아이디·비밀번호·쿠키를 저장하지 않아요.** 네이버에 직접 접속하지도 않아요. 모든 조회는 내가 로그인해 둔 내 브라우저 안에서 일어나요.
- **내 컴퓨터 안에서만 동작해요.** 밖에서는 접속할 수 없고, 연결 키와 확장 확인이라는 이중 잠금이 걸려 있어요.
- **데이터가 나가는 방식** — "연결된 AI 앱이 요청하면 네이버 데이터가 해당 앱과 그 AI 제공사 서버로 전달돼요." 이게 AI가 답하는 방식이라 처음 켤 때 미리 동의를 받아요. 전달된 데이터를 얼마나 보관·학습하는지는 각 AI 제공사 정책을 따르니, 쓰시는 AI 앱의 개인정보 정책을 확인해 주세요.
- **설정에는 정확한 버전이 기록되고, 실행 시 안전한 최신 버전을 확인해요.** 연결 프로그램은 시작할 때와 유휴 상태에서 정본 버전을 확인해 최신 보안·호환 버전으로 승격합니다. 특정 버전을 유지해야 하는 진단 환경은 `--no-self-update`를 사용할 수 있어요.
- **소스가 전부 공개된 오픈소스예요.** 다만 이미 같은 권한으로 실행 중인 악성코드까지 막아 주지는 못해요 — 이 연결 프로그램의 잠금은 원격·타 출처 접근을 막는 장치예요.
## 해지
1. 터미널에서 아래 명령을 실행해요(AI 앱에 등록된 설정을 지워 줘요).
```
npx -y @modootoday/datalab-extension-mcp@1.11.1 uninstall
```
2. 확장 설정에서 **MCP 연결을 꺼요.** 패널이 브릿지라, 꺼 두면 어딘가 설정 줄이 남아 있어도 AI 앱이 아무것도 조회할 수 없어요.
확장을 삭제해도 남은 연결 프로그램은 즉시 무력해져요. 설정에 남은 한 줄은 위 명령으로 지울 수 있고, 안 지워도 아무 일도 하지 않아요.
## 자주 묻는 질문
유료인가요 / ChatGPT 웹 / 항상 켜 두기 / 어떤 데이터 / 다른 컴퓨터
- **유료인가요?** 연결 프로그램 자체는 무료이고 소스가 전부 공개된 오픈소스예요. 다만 AI로 사진을 만들거나 영상에 목소리를 넣는 것처럼 **요금이 드는 기능이 몇 가지 있고**, 그건 실행하기 전에 매번 물어봐요 — 물어보지 않고 요금이 나가는 일은 없어요.
- **ChatGPT 웹사이트에서도 되나요?** 아니요. 컴퓨터에 설치한 데스크톱 앱만 연결돼요.
- **항상 켜 둬야 하나요?** 아니요. 패널이 열려 있을 때만 연결돼요.
- **어떤 데이터를 읽나요?** 블로그 통계·키워드·광고 등 데이터랩툴즈가 보여 주는 것들이에요. 기준은 지금 Chrome에 로그인해 둔 네이버 계정이에요.
- **다른 컴퓨터에서도 되나요?** 네. 컴퓨터마다 한 번씩 설치하고, 연결 키도 컴퓨터마다 따로예요.
## 개발자 부록
소스 검증·통합용 기술 요약 (기술 용어 사용)
- 저장소:
- npm:
**환경 변수**
| 변수 | 필수 | 기본값 | 설명 |
| -------------------------- | ---- | ----------- | ------------------------------------- |
| `DATALAB_MCP_TOKEN` | 필수 | — | 페어링 토큰. 확장 패널에서 발급·폐기. |
| `DATALAB_MCP_EXTENSION_ID` | 필수 | — | 연결을 허용할 확장 ID. |
| `DATALAB_MCP_PORT` | 선택 | `8765` | 수신 포트. |
| `DATALAB_MCP_HOST` | 선택 | `127.0.0.1` | 바인드 주소. loopback 외 값은 거부. |
**호출 한도** — 연결 프로그램 하나가 `10`회까지 몰아 부를 수 있고 초당 `1`회씩 다시 찹니다. 브라우저를 여러 대 연결했다면 그 예산을 **함께 씁니다**. 요금 제한이 아니라 폭주 루프 완충용이라 평범한 사용에서는 닿지 않습니다.
**실패 응답** — 도구 호출 실패는 프로토콜 오류가 아니라 `isError` 결과로 오고, 본문은 성공과 같은 JSON입니다(`ok` / `reason` / `message` / `retryable`, 기다리면 풀리는 경우 `retryAfterMs`). 실패 코드 전체 목록과 각각의 재시도 여부 정본:
**아키텍처** — 연결 프로그램은 자격증명도 egress도 없는 릴레이입니다. 도구 목록은 확장이 서빙하며 카탈로그 정본은 스토어 심사를 받는 확장 코드입니다. 전송은 루프백 HTTP+SSE이며 Origin 검증과 브라우저별 세션 검증을 거치고, 도구 등급 표(조회 / 편집 / 파괴적 / 유료 / 미개방)는 확장 쪽에서 집행됩니다 — 목록에 없는 이름은 거부되고, 파괴적·유료는 세션 허용으로 건너뛸 수 없습니다. allowlist 전문(제외 사유 포함)의 정본:
**공급망** — 공개 저장소가 전체 소스입니다. npm 발행은 OIDC trusted publishing + provenance로 이루어지고 장기 발행 토큰은 쓰지 않습니다(`npm audit signatures`로 검증 가능). 설치 설정은 정확한 bootstrap 버전을 기록하고, 연결 프로그램은 정본 릴리스로 승격할 때도 같은 검증된 npm 패키지 경로를 사용합니다.
**라이선스** — MIT ([LICENSE](./LICENSE)).