Claude Code가 내 노션 페이지를 읽고, 만들고, 고칠 수 있게 MCP로 연결하는 방법입니다. 아래 순서대로 따라 하면 됩니다.
준비물 : 노션 계정, Claude Code가 설치되어 로그인된 터미널.
원리는 단순합니다. 웹(①)에서 토큰을 받고, 노션 앱(②)에서 페이지를 열어준 다음, 터미널(③)에서 둘을 합칩니다. 아래 순서대로 하나씩 따라가면 됩니다.
1. 노션에서 토큰 발급 (5분)
- 브라우저에서 app.notion.com/developers/connections 접속 (노션에 로그인된 상태여야 합니다). 개발자 > 연결 페이지가 열립니다
- 우측 상단 + 신규 연결 클릭
- 연결 이름을 입력합니다. 나중에 목록에서 알아보기 쉽게 연결하는 도구 이름으로 짓는 게 좋습니다 (예:
claude-code) - 인증 방법은 액세스 토큰을 선택합니다(기본값). 설치할 워크스페이스를 고른 뒤 연결 생성하기
- 생성된 연결의 설정 화면에서 액세스 토큰을 복사해 메모장에 잠깐 붙여둡니다.
ntn_으로 시작하는 긴 문자열이 토큰입니다 - 권한에 콘텐츠 읽기 · 콘텐츠 업데이트 · 콘텐츠 삽입 세 개가 켜져 있는지 확인합니다
2. AI에게 열어줄 페이지 정하기 (2분)
방금 만든 연결은 아직 어떤 페이지에도 들어갈 수 없습니다. 연결이 접근할 페이지를 직접 열어줘야 합니다. 모든 페이지를 하나씩 할 필요는 없습니다 (상위 페이지 하나만 열어주면 그 안의 하위 페이지는 자동으로 함께 열립니다).
- 노션에서 AI에게 맡길 페이지를 엽니다
- 페이지 우측 상단 ••• 메뉴 클릭
- Connections → + Add connection
- 아까 만든 연결 이름(
claude-code)을 검색해서 추가 - 확인 창이 뜨면 승인. 이 페이지와 하위 페이지까지 연결에 접근 권한이 설정됩니다
AI는 여기서 허용한 페이지만 볼 수 있습니다. 내 워크스페이스 전체가 아니라, 내가 정한 범위 안에서만 일합니다.
3. Claude Code에 등록 (1분)
터미널을 열고 아래를 입력합니다. ntn_여기에토큰 자리에 1단계에서 복사한 토큰을 붙여넣으면 됩니다.
claude mcp add notion --env NOTION_TOKEN=ntn_여기에토큰 -- npx -y @notionhq/notion-mcp-server
이 명령어를 실행하면 Claude Code에 노션이 등록됩니다. 이제부터 Claude Code가 내 노션을 읽고 쓸 수 있게 됩니다.
토큰 보안 주의. 토큰은 내 노션에 들어가는 열쇠입니다. 남에게 보내거나, 화면 캡처에 포함하거나, git에 올라가는 파일에 적지 마세요. 토큰을 AI 채팅창에 붙여넣어 "대신 설정해줘"라고 시키는 것도 피하세요. 토큰이 대화 기록으로 남습니다. 위 명령어로 직접 등록하는 게 가장 안전합니다.
4. 연결 확인 (1분)
Claude Code를 실행하고 이렇게 물어보세요.
"노션 연결됐는지 확인해줘"
접근 가능한 페이지가 돌아오면 연결 성공입니다. 이어서 쓰기까지 확인해보세요. 2번에서 연결을 추가한 그 페이지 이름을 넣으면 됩니다.
"노션의 OOO 페이지에 '연결 테스트'라는 하위 페이지 만들어줘"
노션에 페이지가 생기면 읽기·쓰기 모두 확인된 겁니다.
안 될 때는 여기부터 확인
- "object not found" / 페이지를 못 찾음 : 90%는 2번(페이지 접근 권한)을 빠뜨린 경우입니다. 페이지 ••• → Connections에 연결이 추가되어 있는지 확인하세요
- notion 서버가 목록에 없음 : Claude Code에서
/mcp를 입력하면 등록된 서버 목록이 보입니다. notion이 없으면 3번 명령을 다시 실행하세요