> ## Documentation Index
> Fetch the complete documentation index at: https://docs-hub.magicmealkits.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 명령줄 도구 mmkhub (베타)

> 터미널과 AI 에이전트에서 허브의 도구를 사용하는 명령줄 도구 mmkhub의 설치, 로그인, 사용 방법. 지금은 베타이며 설치 파일은 곧 공개됩니다.

<Warning>
  **베타, 곧 공개됩니다(Coming soon).** mmkhub는 지금 베타 기간이라 설치 파일을 아직
  공개하지 않았습니다. 공개되면 이 페이지의 설치 명령이 그대로 동작합니다. 공개 소식은
  [릴리스 노트](/ko/release-notes)에서 알려 드립니다.
</Warning>

## 개요

**mmkhub**는 허브에 연결된 Gmail, 캘린더, Drive, YouTube 같은 도구를 터미널에서
사용하는 프로그램입니다. 사람과 AI 에이전트(Claude Code, Codex 등)가 같은 프로그램을
사용합니다.

* **허브의 도구가 그대로 명령이 됩니다.** 허브에 서비스를 연결하면 따로 설치할 것 없이
  `mmkhub gmail ...`, `mmkhub youtube ...` 같은 명령이 생깁니다.
* **큰 파일은 Google에 바로 올립니다.** 영상과 첨부 파일이 허브를 거치지 않습니다.
* **AI 에이전트가 사용하기 좋게 답합니다.** 에이전트가 실행하면 결과를 JSON으로 돌려주고,
  되돌릴 수 없는 명령은 사용자 확인 없이 실행하지 않습니다.
* **허브 로그인으로 연결합니다.** API 키를 만드실 필요가 없습니다.

<Note>
  매직밀키트 CLI(`mmk`)와는 다른 프로그램입니다. 둘을 함께 설치하셔도 서로
  영향을 주지 않습니다.
</Note>

## 설치

### AI에게 설치 맡기기

가장 쉬운 방법입니다. 아래 안내문의 `https://내허브주소`를 내 허브 주소로 바꾼 뒤
Claude Code나 Codex 같은 AI 에이전트에 붙여 넣으세요. AI가 설치하고, 로그인 링크를
보여 드리면 허브에서 허용만 하시면 됩니다.

```text theme={null}
mmkhub(매직밀키트 허브 명령줄 도구)를 설치하고 내 허브에 연결해 줘. 내 허브 주소는 https://내허브주소 야.
1. macOS나 Linux면 터미널에서 curl -fsSL https://github.com/pureugong/mmkhub-releases/releases/latest/download/install.sh | sh 를,
   Windows면 PowerShell에서 irm https://github.com/pureugong/mmkhub-releases/releases/latest/download/install.ps1 | iex 를 실행해.
2. mmkhub auth login --device --start --hub https://내허브주소 를 실행하고, 나온 링크와 코드를 나에게 보여 줘.
   내가 허용했다고 말하면 mmkhub auth login --device --resume 을 실행해.
3. mmkhub skills install 로 사용법을 설치하고, mmkhub auth status 로 연결을 확인해.
토큰은 절대 화면에 출력하지 마.
```

### 직접 설치하기

관리자 권한은 필요하지 않습니다. 설치 스크립트는 받은 파일의 체크섬(SHA256)을 확인하고,
맞지 않으면 아무것도 설치하지 않습니다.

<Tabs>
  <Tab title="macOS, Linux">
    <Steps>
      <Step title="터미널 열기">
        macOS는 Spotlight(⌘ + Space)에서 **터미널**을 검색해 엽니다.
      </Step>

      <Step title="설치 명령 붙여 넣기">
        ```bash theme={null}
        curl -fsSL https://github.com/pureugong/mmkhub-releases/releases/latest/download/install.sh | sh
        ```

        <Frame>
          <img src="https://mintcdn.com/mcp-hub/LYZs_Ri8a1KO1WzK/assets/cli/cli-mac-01-install.png?fit=max&auto=format&n=LYZs_Ri8a1KO1WzK&q=85&s=4f1ab1ff9c0128315ebda61f62de7c3f" alt="터미널 예시 화면. 설치 명령 줄에 밑줄이 있고, PATH 안내 아래의 echo 줄에 빨간 네모가 있다" width="1600" height="455" data-path="assets/cli/cli-mac-01-install.png" />
        </Frame>

        PATH 안내가 나오면 그 아래 `echo`로 시작하는 줄도 그대로 붙여 넣으세요.
        처음 한 번만 하시면 됩니다. `~/.local/bin`에 설치됩니다.
      </Step>

      <Step title="허브에 로그인">
        `https://내허브주소`를 내 허브 주소로 바꿔 실행합니다.

        ```bash theme={null}
        mmkhub auth login --device --hub https://내허브주소
        ```

        <Frame>
          <img src="https://mintcdn.com/mcp-hub/LYZs_Ri8a1KO1WzK/assets/cli/cli-mac-02-login.png?fit=max&auto=format&n=LYZs_Ri8a1KO1WzK&q=85&s=88f4c0e73af30c1791d804e479f5e2ca" alt="터미널 예시 화면. 승인 링크에 빨간 네모, 코드에 빨간 동그라미가 있다" width="1600" height="317" data-path="assets/cli/cli-mac-02-login.png" />
        </Frame>
      </Step>

      <Step title="허브에서 허용">
        <Frame>
          <img src="https://mintcdn.com/mcp-hub/tmVTVz6eOcv1CuGH/assets/muse/03-approve.png?fit=max&auto=format&n=tmVTVz6eOcv1CuGH&q=85&s=23f8ca014d46ce16153a299d0e841320" alt="허브의 기기 연결 승인 화면. 코드, 선택된 주소, 허용 버튼에 빨간 표시가 있다" width="780" height="2716" data-path="assets/muse/03-approve.png" />
        </Frame>

        링크를 열고 허브에 로그인한 뒤, 화면의 코드가 터미널의 코드와 같은지 확인하시고
        **허용**을 누르세요. 터미널은 저절로 이어집니다.
      </Step>

      <Step title="확인하고 사용법 설치">
        ```bash theme={null}
        mmkhub auth status
        mmkhub skills install
        ```

        <Frame>
          <img src="https://mintcdn.com/mcp-hub/LYZs_Ri8a1KO1WzK/assets/cli/cli-mac-03-status.png?fit=max&auto=format&n=LYZs_Ri8a1KO1WzK&q=85&s=f3bb1d48a9ab5b129d1e74d162891f59" alt="터미널 예시 화면. signed_in true 줄과 스킬 설치 경로 줄에 빨간 네모가 있다" width="1600" height="745" data-path="assets/cli/cli-mac-03-status.png" />
        </Frame>

        `signed_in`이 `true`면 연결이 끝났습니다. `skills install`은 AI 에이전트가
        읽을 사용법을 설치합니다.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Windows">
    <Steps>
      <Step title="PowerShell 열기">
        시작 메뉴에서 **PowerShell**을 검색해 엽니다. 관리자 권한은 필요하지 않습니다.
      </Step>

      <Step title="설치 명령 붙여 넣기">
        ```powershell theme={null}
        powershell -ExecutionPolicy Bypass -c "irm https://github.com/pureugong/mmkhub-releases/releases/latest/download/install.ps1 | iex"
        ```

        `%LOCALAPPDATA%\Programs\mmkhub`에 설치되고 PATH에 저절로 추가됩니다.
        설치가 끝나면 PowerShell 창을 닫고 새로 여세요. 그래야 `mmkhub` 명령을 찾습니다.
      </Step>

      <Step title="허브에 로그인">
        ```powershell theme={null}
        mmkhub auth login --device --hub https://내허브주소
        ```

        화면에 링크와 코드가 나옵니다.
      </Step>

      <Step title="허브에서 허용">
        링크를 열고 허브에 로그인한 뒤, 코드가 같은지 확인하시고 **허용**을 누르세요.
        화면은 macOS 탭의 같은 단계와 같습니다.
      </Step>

      <Step title="확인하고 사용법 설치">
        ```powershell theme={null}
        mmkhub auth status
        mmkhub skills install
        ```

        `signed_in`이 `true`면 연결이 끝났습니다.
      </Step>
    </Steps>
  </Tab>
</Tabs>

### 패키지 관리자로 설치하기

Homebrew나 Scoop을 사용하시면 업데이트도 같은 명령으로 하실 수 있습니다.

<Tabs>
  <Tab title="Homebrew (macOS, Linux)">
    ```bash theme={null}
    brew install pureugong/tap/mmkhub
    ```
  </Tab>

  <Tab title="Scoop (Windows)">
    ```powershell theme={null}
    scoop bucket add mmkhub https://github.com/pureugong/scoop-bucket
    scoop install mmkhub
    ```
  </Tab>
</Tabs>

### 직접 내려받기

[릴리스 페이지](https://github.com/pureugong/mmkhub-releases/releases)에서 운영체제에 맞는
압축 파일을 받아 `mmkhub`(Windows는 `mmkhub.exe`)를 PATH에 있는 폴더에 두시면 됩니다.
`SHA256SUMS` 파일로 받은 파일을 확인하실 수 있습니다.

## 사용해 보기

```bash theme={null}
mmkhub tools list                                            # 허브의 도구와, 각각이 바뀐 명령
mmkhub gmail search-threads --account work --query "from:me" # 메일 찾기
mmkhub drive upload 보고서.pdf --account work                 # Drive에 바로 올리기
mmkhub youtube upload 영상.mp4 --account youtube --title "제목" # 비공개로 올라갑니다
mmkhub call gmail_search_threads --json '{"account":"work","query":"from:me"}'
```

허브에 연결된 도구가 모두 명령으로 나옵니다. 메일 보내기나 영상 지우기처럼 되돌릴 수
없는 명령은 실행하기 전에 확인을 받습니다.

## AI 에이전트 모드

Claude Code, Codex 같은 에이전트 안에서 실행되면 mmkhub가 알아서 에이전트 모드로 바뀝니다.

* 결과와 오류를 모두 JSON으로 돌려줍니다. 오류에는 다음에 할 일(`hint`)이 들어 있습니다.
* 메일 보내기, 지우기처럼 되돌릴 수 없는 명령은 `--yes` 없이는 실행하지 않습니다.
  에이전트는 사용자에게 먼저 묻고, 허락을 받은 뒤에 `--yes`를 붙입니다.
* `mmkhub skills install`로 사용법을 설치해 두면 에이전트가 명령을 스스로 찾아 사용합니다.

`--agent`로 에이전트 모드를 켜고, `--no-agent`로 끌 수 있습니다.

## 전역 옵션

| 옵션 | 하는 일 |
| - | - |
| `-o`, `--output` | 출력 형식: `json`, `yaml`, `table`, `ndjson`. 터미널에서는 표, 파이프에서는 JSON이 기본입니다 |
| `-y`, `--yes` | 되돌릴 수 없는 명령을 확인 없이 실행합니다 |
| `--agent`, `--no-agent` | 에이전트 모드를 켜거나 끕니다 |
| `--read-only` | 데이터를 바꾸는 명령을 모두 거부합니다 |
| `--hub` | 허브 주소. 로그인하면 기억합니다 |
| `--jq` | 결과를 jq 식으로 거릅니다 |
| `--page-all` | 다음 페이지가 있으면 끝까지 받아 옵니다 |
| `--from` | JSON 한 줄에 호출 하나씩, 파일이나 표준 입력(`-`)에서 여러 번 실행합니다 |

## 환경 변수

설정하지 않아도 동작합니다. 필요할 때만 바꾸세요.

| 환경 변수 | 하는 일 |
| - | - |
| `MMKHUB_URL` | 허브 주소. 로그인하면 기억하므로 보통 필요 없습니다 |
| `MMKHUB_ACCOUNT` | `--account`의 기본값 |
| `MMKHUB_READ_ONLY` | `true`면 데이터를 바꾸는 명령을 모두 거부합니다 |
| `MMKHUB_OUTPUT` | 출력 형식: `json`, `yaml`, `table`, `ndjson` |
| `MMKHUB_ACCESS_TOKEN`, `MMKHUB_MCP_URL` | 로그인할 수 없는 CI나 샌드박스에서 토큰을 직접 넘길 때 |
| `MMKHUB_CONFIG_DIR` | 로그인 정보를 둘 폴더. 기본은 `~/.config/mmkhub` |
| `MMKHUB_UPLOAD_CHUNK`, `MMKHUB_UPLOAD_RETRIES` | 업로드 조각 크기(바이트)와 재시도 횟수 |
| `MMKHUB_VERSION`, `MMKHUB_INSTALL_DIR` | 설치 스크립트: 설치할 버전과 위치 |

## 지우기

* **macOS, Linux:** `rm ~/.local/bin/mmkhub`, 로그인 정보까지 지우려면 `rm -rf ~/.config/mmkhub`
  (Homebrew로 설치하셨다면 `brew uninstall mmkhub`)
* **Windows:** `%LOCALAPPDATA%\Programs\mmkhub` 폴더와 `%USERPROFILE%\.config\mmkhub` 폴더를 지웁니다
  (Scoop으로 설치하셨다면 `scoop uninstall mmkhub`)

허브 쪽 연결은 관리 화면의 **승인된 커넥터**에서 **MMK Hub CLI**를 해지하세요.

## 문제 해결

<AccordionGroup>
  <Accordion title="설치 명령이 404 또는 Not Found로 끝납니다">
    지금은 베타 기간이라 설치 파일을 아직 공개하지 않았습니다. 공개되면 같은 명령이
    동작합니다.
  </Accordion>

  <Accordion title="command not found: mmkhub">
    설치 폴더가 PATH에 없습니다. macOS는 설치할 때 나온 `echo` 줄을 붙여 넣으시고,
    Windows는 PowerShell 창을 새로 여세요.
  </Accordion>

  <Accordion title="코드가 만료됐다고 나옵니다">
    코드는 10분 동안만 사용하실 수 있습니다. 로그인 명령을 다시 실행하세요.
  </Accordion>

  <Accordion title="Windows에서 스크립트 실행이 막혔다고 나옵니다">
    위의 설치 명령처럼 `powershell -ExecutionPolicy Bypass -c "..."` 형태로 실행하세요.
    이 명령 한 번에만 적용되고 PC 설정은 바뀌지 않습니다.
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.