[Notion Claude] Claude Code와 업무 지식베이스 연결해서 쓰는 방법

안녕하세요. 재아군의 관찰인생입니다.

오늘은 Notion과 Claude Code를 연결해서 사용하는 방법을 정리해보겠습니다. Notion에 쌓인 회의록, 프로젝트 문서, 제품 요구사항, 콘텐츠 캘린더를 Claude Code가 읽고 작업 컨텍스트로 활용하게 만드는 방식입니다.

핵심은 Notion MCP입니다. Notion은 공식 원격 MCP 서버를 제공하고, Claude Code는 MCP를 통해 Notion 같은 외부 도구와 연결할 수 있습니다. 덕분에 별도 크롤러를 만들거나 Notion API 토큰을 직접 관리하지 않아도 OAuth 인증으로 Notion 페이지와 데이터베이스를 활용할 수 있습니다.

핵심 요약: Claude Code에서 claude mcp add --transport http notion https://mcp.notion.com/mcp로 Notion MCP를 추가하고, Claude Code 안에서 /mcp를 실행해 OAuth 인증을 완료하면 Notion 업무 지식베이스를 AI 작업 컨텍스트로 사용할 수 있습니다.

1. Notion Claude 연결은 무엇을 의미하나?

Notion Claude 연결은 Claude Code가 Notion 워크스페이스의 페이지, 데이터베이스, 블록, 문서 내용을 작업에 필요한 맥락으로 가져오게 만드는 구성입니다. 예를 들어 Notion에 적어둔 PRD를 읽고 구현 태스크를 나누거나, 회의록에서 액션 아이템을 뽑아 개발 체크리스트로 정리할 수 있습니다.

이 연결은 Notion 앱 안에서 Claude가 돌아가는 것이 아닙니다. 반대로 Claude Code가 Notion의 MCP 서버를 통해 필요한 정보를 요청하고, 사용자가 허용한 범위 안에서 Notion 데이터를 읽거나 작성하는 구조에 가깝습니다.

구성 요소	역할	활용 예시
Notion	업무 문서와 데이터베이스 저장소	PRD, 회의록, 일정, 지식베이스
Notion MCP	Notion과 AI 도구 사이의 연결 서버	페이지 검색, DB 조회, 문서 작성
Claude Code	Notion 맥락을 이용해 실행하는 AI 작업자	기능 구현, 문서화, 태스크 분해

2. 준비물: Claude Code, Notion 권한, 작업 범위

먼저 Claude Code가 설치되어 있어야 하고, 연결하려는 Notion 워크스페이스에 접근 권한이 있어야 합니다. Notion MCP는 OAuth 인증을 사용하므로, 연결 과정에서 브라우저로 Notion에 로그인하고 어떤 워크스페이스와 페이지를 허용할지 선택하게 됩니다.

연결 전에 가장 중요한 준비는 “어디까지 Claude가 보게 할 것인가”입니다. 개인 메모, 인사 정보, 고객 정보, 비밀 키가 섞인 전체 워크스페이스를 무심코 열어두면 안 됩니다. Notion 문서 구조를 먼저 정리하고, AI가 읽어도 되는 페이지와 데이터베이스를 분리해두는 편이 좋습니다.

• Claude Code CLI가 설치되어 있는지 확인합니다.
• Notion 계정과 워크스페이스 접근 권한을 확인합니다.
• Claude가 읽어도 되는 업무 페이지와 민감한 페이지를 분리합니다.
• 처음에는 읽기 중심 작업부터 시작합니다.
• 대량 작성·수정 작업은 반드시 미리 확인 절차를 넣습니다.

3. Claude Code에 Notion MCP 추가하기

Claude Code 공식 MCP 문서에는 Notion 원격 HTTP 서버 연결 예시가 직접 나와 있습니다. 터미널에서 아래 명령어를 실행하면 Notion MCP 서버가 Claude Code에 등록됩니다.

claude mcp add --transport http notion https://mcp.notion.com/mcp

등록 후에는 Claude Code 세션 안에서 /mcp를 실행합니다. Notion 인증이 필요하면 OAuth 링크가 열리거나 표시되고, 브라우저에서 Notion 로그인과 접근 허용 절차를 마치면 됩니다.

# 연결된 MCP 서버 목록 확인
claude mcp list

# Claude Code 안에서 인증 상태 확인
/mcp

Notion 개발자 문서에서도 권장 연결 방식은 원격 MCP 서버인 https://mcp.notion.com/mcp입니다. 예전 오픈소스 notion-mcp-server를 직접 호스팅하는 방법도 있지만, Notion 문서 기준으로는 대부분의 경우 원격 MCP 서버 사용이 권장됩니다.

4. 연결 후 바로 써볼 수 있는 실전 요청

연결이 끝났다면 Claude Code에 Notion 문서를 기준으로 작업을 시킬 수 있습니다. 핵심은 “Notion에서 찾아봐”가 아니라 어떤 페이지 또는 데이터베이스를 기준으로, 어떤 결과물을, 어디에 만들지를 명확히 말하는 것입니다.

PRD를 개발 태스크로 나누기

Notion의 "모바일 온보딩 개선 PRD" 페이지를 찾아 읽어줘.
요구사항을 프론트엔드, 백엔드, 데이터, QA 태스크로 나눠줘.
각 태스크에는 예상 난이도와 의존성을 붙여줘.
결과는 현재 레포의 docs/onboarding-tasks.md 파일로 작성해줘.

회의록에서 액션 아이템 추출하기

Notion의 "2026-Q2 개발 회의록" 데이터베이스에서 최근 5개 회의록을 확인해줘.
결정사항, 액션 아이템, 담당자, 마감일을 표로 정리해줘.
불명확한 담당자는 "확인 필요"로 표시해줘.

문서와 코드의 차이 찾기

Notion의 "결제 정책 v2" 문서를 읽고,
현재 레포의 결제 관련 코드와 비교해줘.
문서에는 있지만 코드에 없는 규칙,
코드에는 있지만 문서에 없는 규칙을 나눠서 알려줘.
파일 수정은 하지 말고 먼저 리포트만 작성해줘.

5. Notion 데이터베이스를 AI 작업판으로 만드는 구조

Notion과 Claude Code를 잘 연결하려면 Notion 데이터베이스를 사람이 쓰는 표가 아니라 AI가 읽기 좋은 작업판으로 설계해야 합니다. 제목만 있고 본문이 비어 있거나 상태값이 제각각이면 Claude가 맥락을 정확히 파악하기 어렵습니다.

데이터베이스	추천 속성	Claude Code 활용
PRD	상태, 담당자, 우선순위, 릴리즈	개발 태스크 분해
회의록	날짜, 참석자, 결정사항, 액션 아이템	후속 작업 추출
버그 리포트	재현 단계, 영향도, 환경, 상태	디버깅 계획 수립
콘텐츠 캘린더	키워드, 채널, 발행일, 상태	초안 생성과 리ライト

6. 프로젝트별 설정 범위: local, project, user 선택하기

Claude Code MCP 설정에는 범위(scope)가 있습니다. 개인용으로 여러 프로젝트에서 Notion을 쓰려면 user 범위가 편하고, 특정 레포에서만 쓰려면 local 범위가 안전합니다. 팀이 공유하는 설정은 project 범위를 쓸 수 있지만, 인증과 권한 이슈를 신중히 다뤄야 합니다.

# 현재 프로젝트에서만 사용
claude mcp add --transport http notion --scope local https://mcp.notion.com/mcp

# 내 계정의 여러 프로젝트에서 사용
claude mcp add --transport http notion --scope user https://mcp.notion.com/mcp

# 연결 정보 확인
claude mcp get notion

업무용 Notion은 개인 지식베이스보다 민감도가 높습니다. 기본값으로 전체 프로젝트에 공유하기보다, 처음에는 local 또는 user 범위로 시작하고 팀 공유가 필요할 때만 project 설정을 검토하는 편이 좋습니다.

7. 보안 체크리스트: 연결보다 권한 설계가 먼저입니다

Notion 공식 문서에 따르면 연결 또는 integration은 권한과 공유 범위에 따라 접근 가능한 콘텐츠가 달라집니다. 또한 capabilities는 어떤 API 엔드포인트와 콘텐츠에 접근할 수 있는지를 제한합니다. 즉, 연결 자체보다 중요한 것은 최소 권한과 접근 범위입니다.

• 처음 연결할 때 모든 페이지를 열지 말고 필요한 페이지부터 허용합니다.
• 고객 정보, 계약서, 인사 문서가 있는 데이터베이스는 분리합니다.
• Claude Code에게 “바로 수정하지 말고 먼저 리포트만 작성”하도록 지시합니다.
• Notion에 쓰기 작업을 시킬 때는 변경할 페이지와 형식을 명확히 제한합니다.
• 인증 문제가 생기면 Claude Code의 /mcp에서 인증을 초기화하고 다시 연결합니다.

마무리: Notion Claude 조합은 업무 맥락을 코드 작업으로 가져오는 연결입니다

Notion Claude 연결의 가치는 Notion을 단순히 검색하는 데 있지 않습니다. 팀의 결정사항, 요구사항, 정책 문서, 회의록을 Claude Code의 작업 컨텍스트로 가져와 실제 코드·문서·체크리스트 작업으로 이어지게 만드는 데 있습니다.

가장 현실적인 시작 순서는 간단합니다. Notion MCP를 Claude Code에 추가하고, /mcp로 OAuth 인증을 마친 뒤, 읽기 중심 요청부터 테스트하세요. 이후 신뢰가 쌓이면 Notion 페이지 작성, 데이터베이스 업데이트, 코드 변경 계획 수립까지 확장하면 됩니다.

참고 자료

• Claude Code Docs: Connect Claude Code to tools via MCP
• Notion Developers: Connecting to Notion MCP
• Notion Help: Notion MCP
• Notion Developers: Authorization
• Notion Developers: Integration capabilities

Notion Claude 워크플로우는 연결 명령어 하나보다 권한 설계와 데이터베이스 구조가 더 중요합니다. 작게 연결하고, 읽기부터 검증하고, 쓰기 작업은 승인 절차를 둔 뒤 확장하세요.