Notion MCP

Notion 공식 원격 MCP 서버 — Notion이 직접 호스팅

왜 필요한가?

개발 중 Notion에 정리된 기획 문서나 작업 목록을 확인하려면 브라우저로 전환해야 합니다. Notion MCP를 연결하면 Claude Code에서 직접 워크스페이스를 검색하고, 문서를 작성하고, 프로젝트 상태를 업데이트할 수 있습니다.

연결 방법

1. Claude Code CLI

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

연결 후 Claude Code에서 /mcp 명령어를 실행하면 OAuth 인증 링크가 제공됩니다. 브라우저에서 Notion 계정으로 로그인하면 연결이 완료됩니다.

2. Notion 설정에서 연결

Notion → 설정 → 연동 → Notion MCP에서 직접 연결할 수도 있습니다.

범위 옵션

옵션	설명
--scope local (기본값)	현재 프로젝트에서만 사용
--scope project	.mcp.json을 통해 팀 전체 공유
--scope user	내 모든 프로젝트에서 사용

주요 기능

• 페이지 검색 — 워크스페이스 전체 콘텐츠 검색
• 문서 작성 — PRD, 기술 사양서, 릴리스 노트 자동 생성
• 데이터베이스 쿼리 — 프로젝트 진행 현황 조회 및 업데이트
• 콘텐츠 편집 — 마크다운 기반 페이지 수정

Before / After

Before: 코딩 → 브라우저에서 Notion 열기 → 기획 문서 검색 → 내용 확인 → 에디터로 복귀

After: “Notion에서 로그인 기능 기획 문서 찾아줘” → 즉시 조회 → 구현 후 작업 상태 자동 업데이트

실제 사용 시나리오

1. 기획 문서를 검색하여 요구사항을 확인하고, 구현 완료 후 Notion 작업 상태를 자동 업데이트
2. 코드 변경 사항을 기반으로 릴리스 노트를 Notion에 자동 생성
3. Notion 데이터베이스를 쿼리하여 프로젝트 진행 현황을 한눈에 파악

알아두면 좋은 점

• 이미지/파일 업로드는 현재 미지원
• OAuth 인증이 필요하므로 완전 자동화(헤드리스) 환경에서는 사용 불가
• /context 명령어로 현재 토큰 사용량 확인 가능
• Claude Code 플러그인 마켓플레이스에도 등록되어 있어 Skills·슬래시 커맨드 포함 버전 설치 가능