# 노션에서 GPT Image 2로 그림 그리기

노션 AI가 OpenAI의 `gpt-image-2`로 이미지를 만들어 **노션 페이지에 바로 넣어주는** 서버입니다.

노션에 이렇게 말하면 됩니다.

> OpenAI로 이 페이지 표지 이미지 만들어줘

---

## 잠깐, 이거 꼭 필요하신가요?

**노션 AI에도 이미지 생성이 이미 있습니다.** 구글 제미나이의 **나노 바나나**(Nano Banana) 엔진을 씁니다. 노션에 그냥 말하면 나오고, 설치할 것도 카드 등록할 것도 없습니다.

**이 서버는 나노 바나나 대신 OpenAI의 `gpt-image-2`를 꼭 쓰고 싶을 때 설치합니다.** 그게 아니라면 노션 기본 기능으로 충분합니다.

덤으로 따라오는 것:

- **4K(3840×2160)** 같은 큰 해상도와 정확한 비율 지정
- 노션 AI 이미지 생성 한도와 무관하게 사용 (대신 OpenAI에 직접 요금을 냅니다)

---

## 어떻게 돌아가나요

노션 AI는 OpenAI를 직접 부르지 못합니다. 노션 안에 그런 기능이 없으니까요.

그런데 노션에 **사용자 지정 MCP 서버 연결**이 열렸습니다. MCP는 AI에게 바깥 도구를 쥐어주는 공통 규격입니다. 노션이 "이 규격에 맞는 서버를 가져오면 내 AI가 그걸 도구로 쓰겠다"고 문을 하나 내준 셈입니다.

그래서 이 설치가 하는 일은 결국 이렇습니다.

1. `gpt-image-2`를 부를 줄 아는 **MCP 서버를 하나 만든다** — 1단계 버튼이 대신 해줍니다
2. 그 서버를 **노션에 연결한다** — 4단계
3. 노션 AI가 **그림 그리는 도구를 하나 갖게 된다**

노션에 없는 기능을 직접 만들어 갖다 붙이는 것입니다. 만드는 쪽은 버튼 하나로 끝나고, 실제로 품이 드는 건 키를 모으는 2·3단계입니다.

```mermaid
flowchart LR
  U["🧑 나"] -->|"표지 이미지<br/>만들어줘"| N["노션 AI"]
  N -->|"① MCP_TOKEN"| W["내 MCP 서버<br/>Cloudflare"]
  W -->|"② OPENAI_API_KEY"| O["OpenAI<br/>gpt-image-2"]
  O -.->|"완성된 이미지"| W
  W -->|"③ NOTION_API_KEY"| P["📄 노션 페이지"]
```

가운데 **내 MCP 서버**가 이번에 만드는 물건입니다. 설치할 때 입력하는 **키 세 개가 각각 화살표 하나**입니다.

| 키 | 하는 일 | 없으면 |
| --- | --- | --- |
| `MCP_TOKEN` | 노션이 **내 서버에** 들어올 때 쓰는 비밀번호. 내가 직접 정합니다 | 아무나 내 서버를 쓸 수 있습니다 |
| `OPENAI_API_KEY` | 내 서버가 **OpenAI에** 그림을 주문할 때 쓰는 키 | 이미지가 안 만들어집니다 |
| `NOTION_API_KEY` | 내 서버가 **노션 페이지에** 결과를 붙일 때 쓰는 키 | 링크만 받고, 붙여넣기는 직접 |

서버는 Cloudflare에서 돌아갑니다. 평소에는 꺼져 있다가 **요청이 올 때만 깨어나는** 방식이라 안 쓰면 요금이 나오지 않습니다. 실제로 돈이 나가는 건 위 그림에서 **② 하나뿐**입니다.

---

## 미리 아셔야 할 것

**돈이 듭니다.** 이미지 한 장 만들 때마다 OpenAI에 요금이 부과됩니다. 본인이 등록한 본인 카드에서 나갑니다. 설치할 때 **사용 한도**를 꼭 걸어두세요 — 2단계에서 안내합니다.

**노션 AI 크레딧은 따로 쓰지 않습니다.** MCP 도구를 부르는 것 자체에는 노션 AI 사용량이 들지 않습니다. 요금은 OpenAI 쪽에서만 나갑니다.

**시간이 걸립니다.** 실제로 측정한 값입니다.

| 화질 | 걸리는 시간 |
| --- | --- |
| 시안 | 약 19초 |
| 최종본 | 약 84초 |
| 인쇄용 4K | 약 95초 |

**계정이 세 개 필요합니다.** Cloudflare(서버 운영, 무료), OpenAI(유료), 노션(이미 있으실 겁니다).

전부 합쳐 **20~30분** 정도 걸립니다.

---

## 1단계 — 서버 배포하기

아래 버튼을 누르면 Cloudflare가 알아서 서버를 만들어 줍니다. 터미널이나 프로그램 설치는 필요 없습니다.

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/1000ssam/notion-gpt-image-mcp)

1. 버튼을 누릅니다
2. Cloudflare 계정으로 로그인합니다 (없으면 무료로 가입)
3. GitHub 연결을 허용합니다 — 이 코드가 본인 계정으로 복사됩니다
4. **키 세 개를 입력하는 화면**이 나옵니다. 여기서 잠깐 멈추고 2·3단계를 먼저 하세요

> 이미지 저장소와 작업 큐는 **자동으로 만들어집니다.** 따로 설정하실 것 없습니다.

---

## 2단계 — OpenAI 키 만들기 (제일 오래 걸립니다)

여기가 가장 막히기 쉬운 곳입니다. 순서대로 하세요.

### 2-1. 결제수단 등록

[platform.openai.com/settings/organization/billing](https://platform.openai.com/settings/organization/billing) 에서 카드를 등록하고 **크레딧을 충전**합니다. 처음이면 5~10달러로 시작해도 충분합니다.

### 2-2. 사용 한도 걸기 ⚠️ 건너뛰지 마세요

**Settings → Limits** 에서 월 사용 한도(Monthly budget)를 정합니다.

이걸 안 하면 두 가지가 문제입니다.

- 한도가 0이면 **결제수단을 등록해도 이미지가 안 만들어집니다** (`billing_hard_limit_reached` 오류)
- 한도가 없으면 실수나 사고로 요금이 계속 나갈 수 있습니다

**월 10달러 정도로 걸어두시길 권합니다.** 넘으면 그냥 멈춥니다. 넘겨서 청구되지 않습니다.

### 2-3. 키 발급

[platform.openai.com/api-keys](https://platform.openai.com/api-keys) 에서 `Create new secret key`.

**키는 이때 한 번만 보입니다.** 창을 닫으면 다시 못 봅니다. 바로 복사해 두세요.

---

## 3단계 — 노션 통합 만들기

이미지를 노션 페이지에 **직접 넣고 싶을 때만** 필요합니다. 링크만 받아도 괜찮으면 건너뛰세요.

1. [notion.so/profile/integrations](https://www.notion.so/profile/integrations) → `새 API 통합`
2. 이름을 짓고(예: `이미지 생성`), 본인 워크스페이스를 고릅니다
3. 만들어진 **내부 통합 시크릿**(`ntn_` 으로 시작)을 복사합니다
4. **이미지를 넣을 페이지로 가서** 우측 상단 `···` → `연결` → 방금 만든 통합을 추가합니다

> 4번을 빼먹으면 "페이지를 찾을 수 없다"는 오류가 납니다. 노션은 페이지마다 따로 허용해야 합니다.

### 키 세 개를 다 모았습니다

1단계에서 멈춰둔 설치 화면으로 돌아가 채웁니다.

| 칸 | 넣을 값 |
| --- | --- |
| `OPENAI_API_KEY` | 2단계에서 복사한 키 |
| `MCP_TOKEN` | **직접 정하는 비밀번호.** 길고 아무도 못 맞출 문자열로 (예: `sunflower-8842-teacup-quiet-lamp`) |
| `NOTION_API_KEY` | 3단계의 `ntn_...` 키 (안 쓰면 비워두기) |

배포가 끝나면 **주소가 나옵니다.** `https://무언가.workers.dev` 형태입니다. **이 주소와 방금 정한 비밀번호를 적어두세요.** 다음 단계에서 씁니다.

---

## 4단계 — 노션에 연결하기

> ⚠️ 노션 **Business 또는 Enterprise 플랜**에서만 됩니다. 개인 플랜에는 이 기능이 없습니다.

### 4-1. 워크스페이스 설정 켜기

`설정` → `연결` → `관리` 탭 → **"사용자 지정 MCP 서버 활성화"** 를 켭니다.

이게 꺼져 있으면 다음 단계에서 메뉴가 아예 안 보입니다.

### 4-2. 서버 연결하기

`연결 추가` → **`사용자 지정 MCP 서버`**

| 칸 | 넣을 값 |
| --- | --- |
| URL | 3단계에서 받은 주소 뒤에 `/mcp` 를 붙입니다 |
| 인증 | 직접 정한 `MCP_TOKEN` 비밀번호 |

예: `https://notion-gpt-image-mcp.내계정.workers.dev/mcp`

연결되면 도구 다섯 개가 나타납니다.

### 4-3. 실행 방식은 "항상 확인"으로

도구마다 `자동 실행` / `항상 확인`을 고를 수 있습니다.

**전부 `항상 확인`으로 두고 시작하세요.** 이미지 생성은 호출할 때마다 돈이 나갑니다. 몇 번 써보고 익숙해지면 하나씩 푸세요.

---

## 다 됐습니다

노션에서 이렇게 말해보세요.

> OpenAI로 정사각형 시안 이미지 하나 만들어줘. 노란 레몬 한 개, 흰 배경, 미니멀하게.

처음엔 **시안(약 19초)** 으로 해보세요. 잘 나오면 최종본으로 다시 뽑으면 됩니다.

---

## 잘 안 될 때

| 증상 | 원인과 해결 |
| --- | --- |
| `billing_hard_limit_reached` | 사용 한도가 0이거나 이미 다 썼습니다. **2-2단계**를 다시 보세요. 결제수단 등록만으로는 안 풀립니다 |
| `insufficient_quota` | 크레딧 잔액이 없습니다. 충전하세요 |
| 연결할 때 `401` | 비밀번호가 다릅니다. 배포할 때 넣은 `MCP_TOKEN`과 노션에 넣은 값이 같은지 확인하세요 |
| `사용자 지정 MCP 서버` 메뉴가 없음 | **4-1단계**가 꺼져 있거나, 노션 플랜이 Business 미만입니다 |
| 페이지에 이미지가 안 들어감 | 그 페이지에 통합을 연결하지 않았습니다. **3단계 4번**을 하세요 |
| 고화질이 중간에 끊김 | 최종본은 84초가 걸립니다. 아래 지침을 넣어두면 기다립니다 |
| `unsupported_country_region_territory` | OpenAI가 막는 지역에서 요청이 나갔습니다. 이 서버는 미국 경유로 고정해 뒀으니 정상적으로는 안 납니다. 나면 Issues로 알려주세요 |

---

## 잘 시키는 법

노션 AI에 지침을 미리 넣어둘 수 있다면 아래를 넣어두세요. 없으면 처음 요청할 때 한 번 붙여넣어도 됩니다.

```text
사용자가 OpenAI로 이미지를 만들라고 하면 이 MCP를 사용한다.
- 빠른 시안: generate_image, quality "low"
- 최종본이나 큰 이미지: start_image_job 을 부르고 get_image_job 을
  몇 초 간격으로 폴링한다. 고화질은 20~120초 걸리므로 4회 폴링 전에
  포기하지 않는다.
- 페이지에 넣으려면 page_id 를 넘긴다. 모르면 find_page 로 찾고
  사용자에게 맞는지 확인한다.
- 사용자 설명을 구체적인 영어 이미지 프롬프트로 옮긴다.
- 결과에 image_url 과 사용한 크기·화질을 함께 보고한다.
```

---

## 도구 다섯 개

| 도구 | 하는 일 |
| --- | --- |
| `ping` | 연결 확인. 무료 |
| `find_page` | 제목으로 노션 페이지 찾기 |
| `generate_image` | 만들고 기다림. 시안용 |
| `start_image_job` | 큐에 넣고 바로 반환. 고화질·4K용 |
| `get_image_job` | 진행 상황 확인 |

### 크기

프리셋: `square`(1024×1024) · `landscape`(1536×1024) · `portrait`(1024×1536) · `wide_16_9`(2048×1152) · `tall_9_16`(1152×2048) · `uhd_16_9`(3840×2160)

`"1536x1024"` 처럼 직접 지정할 수도 있습니다. 양변이 16의 배수, 최대 3840, 비율 3:1 이내여야 합니다.

---

## 안전하게 쓰기

- **`MCP_TOKEN`을 남에게 주지 마세요.** 이 값 하나로 남이 내 OpenAI 요금을 쓰고, 통합이 연결된 노션 페이지를 검색·수정할 수 있습니다.
- **노션 통합은 필요한 페이지에만 연결하세요.** 워크스페이스 전체에 연결하면 사고 범위가 커집니다.
- **이미지 주소는 공개입니다.** 주소를 아는 사람은 볼 수 있습니다(주소 자체는 추측 불가능한 무작위 값). 민감한 이미지는 만들지 마세요.
- **OpenAI 사용 한도**가 유일한 요금 상한입니다. 꼭 걸어두세요.

비밀번호를 바꾸려면 Cloudflare 대시보드 → 해당 Worker → `Settings` → `Variables and Secrets` 에서 `MCP_TOKEN`을 교체하고, 노션 연결 설정에서도 같이 바꾸면 됩니다.

---

## 개발자용

구조, 설계 근거, 로컬 실행, 검증 스크립트는 [DEVELOPING.md](DEVELOPING.md)에 있습니다.

이 리포지토리는 공개돼 있습니다. 설치 전에 코드를 직접 확인하실 수 있습니다.

문제나 개선 제안은 Issues로 남겨주세요. MIT 라이선스입니다.