노션 워크스페이스 연동해서 노션 페이지를 로컬(md)로 다운로드해본 사례 🗂️
2026.01.26

소개
스터디 과정 중 노션 워크스페이스 연동 실습이 포함되어 있어서, 미리 세팅하는 김에 노션에 정리해두었던 활동 기록들을 로컬 환경에 백업해보았다.
노션에 스터디 및 개인 활동 기록을 꾸준히 정리해둔 상태
추후를 대비해 로컬 폴더 구조 안에 md 파일 형태로 보관하면 좋겠다고 판단
단순 실습이 아니라, 실제로 끝까지 다운로드가 되는지 확인해보고 싶었음
진행 방법
사용한 도구 및 환경
Notion (페이지 원본)
Notion API (연동용)
Claude Code (오류 원인 분석 & 코드 수정 도움)
VS Code (작업용 에디터)
Windows + PowerShell
결과물: Markdown (.md) 파일
1️⃣ Notion API 키 발급 & 페이지 ID 확인
Notion → My integrations 에서 API 키 발급
다운로드하고 싶은 페이지를 노션에서 선택
페이지 URL에서 Page ID 추출
👉 여기까지는 비교적 수월하게 진행됨
2️⃣ .env 파일에서 첫 번째 막힘
워크스페이스 루트에
.env파일을 직접 만들어야 했는데 여기서 잠깐 멈춤제공받은 폴더 안에
.env.example파일이 있어서:해당 내용을 복사
myenv.env파일을 새로 생성해서 붙여넣기
이 과정에서 env 파일의 역할(환경 변수 관리)을 Claude Code가 설명해줘서 이해함
3️⃣ 패키지 설치 & 가상환경 이슈
PowerShell에서 패키지 설치를 시도하다가 오류 발생 → Claude Code에 아래 코드에 대해 질문
.\.venv\Scripts\Activate.ps1
python -m pip install -r .claude\skills\notion-down-lv2\requirements.txt
첫 줄: PowerShell에서 가상환경 활성화
두 번째 줄: Python 모듈 설치
문제: 가상환경(.venv)이 아직 생성되지 않은 상태
👉 VS Code 터미널에서 가상환경을 먼저 생성
python -m venv .venv
그 후 다시 활성화 시도했더니 보안 오류 발생
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
위 명령어 실행 후 가상환경 활성화 성공 🎉
4️⃣ SyntaxError와 환경 변수 이름 문제
페이지 다운로드 실행 시 다음 오류 발생:
SyntaxError: from __future__ imports must occur at the beginning of the file
오류가 난
.py파일로 이동from __future__ import ...구문을 파일 최상단으로 이동 → 해결
그 다음 발생한 오류:
.env파일에NOTION_TOKEN이 없다는 메시지
원인 분석:
.py파일에서는.env경로를".env"로 지정실제 파일명은
myenv.envenv 파일 안 변수명도
NOTION_API_TOKEN=으로 되어 있었음
👉 수정한 내용
env 경로를
myenv.env로 변경변수명을
NOTION_TOKEN=으로 통일
5️⃣ Notion AI 블록으로 인한 오류
다운로드 중 아주 긴 오류 메시지 발생
Claude Code에 오류 로그를 그대로 전달
원인: 노션 페이지에 포함된 AI 블록
해당 블록 타입은 Notion API에서 지원하지 않음
Notion 페이지에 AI 블록(Notion AI가 생성한 콘텐츠)이 있어서 발생하는 오류입니다. Notion API가 ai_block 타입을 지원하지 않습니다.해결 방법스크립트에서 지원하지 않는 블록을 건너뛰도록 수정하면 됩니다. 해당 스크립트를 확인해볼게요.Read c:\Users\AI-WORKSPACE\.claude\skills\notion-down-lv2\scripts\notion_download_tree.pyblocks_to_markdown 함수에서 ai_block을 처리하지 않아서 발생하는 오류입니다. 지원하지 않는 블록 타입을 건너뛰도록 수정할게요.Edit c:\Users\AI-WORKSPACE\.claude\skills\notion-down-lv2\scripts\notion_download_tree.pyAdded 8 linesRead c:\Users\AI-WORKSPACE\.claude\skills\notion-down-lv2\scripts\notion_download_tree.py (lines 107-166)중복된 줄이 있네요. 제거할게요.Edit c:\Users\AI-WORKSPACE\.claude\skills\notion-down-lv2\scripts\notion_download_tree.pyModified수정 완료했습니다. 이제 다시 실행해보세요.
👉 해결 방법
ai_block타입을 만나면:내용을 건너뛰고
md 파일에는 주석으로 표시하도록 코드 수정
# 지원하지 않는 블록 타입은 skip 처리
이후 다운로드 정상 완료 🎉

결과와 배운 점
결과
원래는 데이터베이스 + 하위 페이지 2개가 포함된 페이지를 다운로드할 계획이었음
실제로는 데이터베이스는 제외되고, 하위 페이지 2개만 md 파일로 다운로드됨
하위 페이지 내에서 Notion AI로 생성된 블록은 아래와 같이 표시됨
<!-- [Notion unsupported: API에서 지원하지 않음] -->

AI 블록을 제외한 나머지 본문, 제목, 구조는 비교적 잘 유지됨
결과적으로 문서형 페이지 백업 용도로는 충분히 만족스러운 결과였음
배운 점 & 인사이트
NOTION_DOWNLOAD_DEFAULT_PAGE_ID가 parent page로 인식되면서, 해당 페이지 하위에 있는 child page만 다운로드 대상이 된 것으로 보임이 구조상 데이터베이스는 child page로 취급되지 않아 결과물에서 제외된 것으로 추정됨
즉, 어떤 ID를 기준으로 삼느냐에 따라 다운로드 결과가 크게 달라질 수 있음
Notion API는 모든 블록 타입을 지원하지는 않음
.env, 가상환경, PowerShell 보안 정책은 Windows 환경에서 특히 자주 막히는 포인트오류 메시지를 그대로 AI에게 던져주고 하나씩 분해해서 해결하는 방식이 꽤 효과적이었음
다음에 한다면
대시보드처럼 사용하는 상위 집계용 페이지 ID를
NOTION_DOWNLOAD_DEFAULT_PAGE_ID로 지정하면,그 아래에 연결된 여러 페이지들이 연쇄적으로 다운로드되는지 확인해볼 계획
만약 이 방식이 통한다면:
노션을 대시보드 중심으로 설계 →
로컬 백업 시에는 하나의 진입점(Page ID)만 관리하는 구조가 가능할 것 같음
데이터베이스가 포함된 경우에는 여전히 별도 처리가 필요할 것으로 예상됨
스터디 시작 전에 미리 세팅해두면 훨씬 수월할 듯
자동화까지는 아니어도 정기 백업 용도로는 충분히 실용적
한 줄 정리 ✍️
노션 페이지 로컬 백업, 한 번 세팅은 빡세지만 해두면 마음이 편해진다 😅




선해라님 드디어!!! Notion API 연동까지 성공하셨네요. 한번 세팅은 빡세지만 ㅋㅋㅋ ai_block 미지원 이슈, PowerShell 가상환경 문제 등 기술적 허들을 차근차근 해결하시고 마음이 편해진 그 과정이 정말 좋습니다.
.env 파일로 API 키 관리 정말 필요해요! 자칫하다 유출되면 큰일이니까요! 잠깐 멈칫하셨지만 이번에 env 파일 역할을 확실히 이해하셨으니, 정말 큰 도움 되셨을 거라 생각 들어요. skip 처리로 ai_block 문제를 우회하신 것도 실용적인 방법인 것 같아요. 워크스페이스든, 어떤 일이든 이젠 완벽한 해결이 아니어도 일단 돌아가게 만든 후 조금씩 손보면서 완성도를 높이는 게 중요하다고 생각합니다.
Notion 데이터를 로컬 마크다운으로 가져오면 백업도 되고, 옵시디언에서 활용도 가능해지고, 여러모로 유용해요. 플랫폼 종속에서 벗어나는 첫 걸음이기도 하고요. 다른 분들도 Notion 연동 많이 궁금해하시는데, 좋은 참고 사례가 될 것 같아요 :)