Claude Code용 Notion MCP 공식 호스팅 서버 설정
당신의 사양서, 회의 메모, 버그 티켓은 Notion에 있습니다. 당신의 코드는 Claude Code에 있습니다. 그래서 모든 작업은 늘 같은 의식으로 시작됩니다. Notion 페이지를 열고, 요구사항을 복사해 터미널에 붙여넣고, 범위가 바뀐 아래쪽 댓글 스레드를 놓치지 않았기를 바라며 진행하는 것입니다.
Notion MCP는 mcp.notion.com에서 제공되는 Notion의 공식 호스팅 MCP 서버입니다. Claude Code는 OAuth를 통해 Notion 계정으로 로그인하며, 그다음부터는 사용자가 이미 볼 수 있는 범위 안에서만 워크스페이스를 검색하고, 페이지와 데이터베이스를 Markdown으로 읽고, 페이지를 생성하거나 업데이트할 수 있습니다. API 토큰도, JSON 설정도, 로컬에서 실행할 것도 없습니다.
주의: 검색 결과는 여전히 예전의 자체 호스팅 패키지(@notionhq/notion-mcp-server)를 가리킵니다. Notion의 자체 README는 이제 그 저장소가 더 이상 적극적으로 유지보수되지 않는다고 밝히며, 대신 호스팅 서버를 권장합니다. 이 가이드는 바로 그 버전을 설정합니다. 마찬가지 이유로 커뮤니티 MCP 추천 목록에서도 방치된 서버는 제외합니다.
빠른 시작
한 번의 명령으로 모든 프로젝트에 추가할 수 있습니다:
claude mcp add --transport http --scope user notion https://mcp.notion.com/mcp그다음 로그인합니다: Claude Code 안에서 /mcp를 실행하고 notion 을 선택한 뒤, 열리는 브라우저 창에서 접근을 승인하세요. 걸리는 시간은 총 약 2분입니다.
⚡ 이 프롬프트를 복사하세요: Claude Code가 설치와 검증을 직접 하게 하기
아래의 수동 단계를 건너뛰고, 대신 전체 작업을 에이전트에게 맡기세요:
You have shell access and the `claude mcp` CLI on this machine. Connect Notion's official hosted MCP server to Claude Code and report back. Do not tell me it's done unless step 5 actually confirms it:
1. Run `claude mcp list`. If a notion entry already exists, show me its command or URL. If it runs `npx @notionhq/notion-mcp-server` (the old self-hosted server), tell me and ask before replacing it.
2. If there's no hosted entry, add it for all projects:
`claude mcp add --transport http --scope user notion https://mcp.notion.com/mcp`
3. Tell me to run `/mcp` inside Claude Code (or `claude mcp login notion` in a terminal) and complete the Notion sign-in in my browser. Wait for me to confirm. Never ask me for a Notion token or integration secret; this server uses OAuth only.
4. Run `claude mcp list` and confirm notion shows Connected.
5. Search my Notion workspace for any page (use a short keyword like "meeting") and show me the titles of up to 3 results. Read only; do not create or edit any page.
If any step fails, give me the exact error and the command that produced it. Do not skip ahead.에이전트가 Notion의 로그인 페이지에서 직접 “Allow”를 클릭해 줄 수는 없으므로, 프롬프트는 그 지점에서 멈춥니다. 또한 오래된 자체 호스팅 서버도 확인하므로 Notion 항목이 두 개로 중복되는 일을 막을 수 있습니다.
준비물
| 필요 사항 | 필요한 이유 | 소요 시간 |
|---|---|---|
| Notion 계정 | 어떤 플랜이든 괜찮습니다. 일부 검색 필터와 연결된 앱 전반의 AI 검색은 Business 또는 Enterprise가 필요합니다 | 0분 |
| Claude Code 설치 | 호스팅 서버에 연결하는 클라이언트입니다 | 0분 |
| 같은 머신의 브라우저 | OAuth 로그인 시 Notion 승인 페이지가 열립니다 | 1분 |
단계별 설정
에이전트에게 맡기지 않고 직접 하길 원하시나요? 수동 버전은 다음과 같습니다.
1단계 — 호스팅 서버 추가
~30초
--scope user를 사용하면 모든 프로젝트에서 Notion을 사용할 수 있습니다. 대신 --scope project를 사용하면 저장소 안의 .mcp.json 파일을 통해 팀과 공유할 수 있습니다:
claude mcp add --transport http --scope user notion https://mcp.notion.com/mcp
2026년 10월의 실제 실행 화면입니다. 인증 필요라는 메시지는 서버에 접속할 수 있고 여러분을 기다리고 있다는 뜻입니다. claude 안에서 /mcp를 실행해 로그인하세요.
2단계 — OAuth로 로그인
~1분
Claude Code 안에서 /mcp를 실행하고 notion 을 선택한 다음 브라우저 안내를 따르세요. 터미널 방식이 더 좋다면, 세션을 열지 않고도 같은 로그인 과정을 실행할 수 있습니다:
claude mcp login notionClaude가 접근할 워크스페이스를 선택하세요. 항목당 하나의 워크스페이스만 연결할 수 있습니다.
3단계 — 사용하는 컨텍스트 양 확인
~30초
모든 MCP 서버는 Claude의 컨텍스트에 도구 정의를 추가합니다. Claude Code에서 /context를 실행해 Notion이 얼마나 많은 토큰을 사용하는지 확인하고, 다른 서버와 비교해 보세요.
한 번의 OAuth 로그인만 마치면 터미널에서 읽을 수 있는 당신의 Notion 페이지와 데이터베이스입니다.
각 구성 요소의 역할
| 도구 | Claude가 이를 통해 할 수 있는 일 |
|---|---|
| notion-search / notion-ai-search | 키워드로 페이지를 찾습니다. AI 검색은 요금제에 Notion AI가 포함되어 있으면 Slack, Google Drive 같은 연결된 앱도 함께 검색합니다 |
| notion-fetch | URL 또는 ID로 페이지, 데이터베이스, 데이터 소스를 읽습니다. 스키마와 템플릿도 포함됩니다 |
| notion-create-pages / notion-update-page | 새 페이지를 만들거나 기존 페이지를 수정합니다. 예를 들어 상태 속성을 채우거나 메모를 덧붙일 수 있습니다 |
| notion-query-data-sources | 데이터베이스 행을 조회합니다. 예를 들어 “Ready for dev”로 표시된 모든 티켓을 찾을 수 있습니다 |
| notion-create-comment / notion-get-comments | 페이지 댓글을 읽고 추가합니다. 실제 결정이 오가는 토론 스레드도 포함됩니다 |
| OAuth 권한 | Claude는 사용자의 Notion 계정이 볼 수 있는 것만 정확히 봅니다. 워크스페이스 소유자는 Settings → Connections에서 연결을 검토하고 해제할 수 있습니다 |
실제로 작동하는지 확인하기
claude mcp list✔ notion https://mcp.notion.com/mcp (HTTP) – 연결됨
! notion 인증 필요 → /mcp를 실행하고 로그인 절차를 완료하세요
✘ notionApi npx @notionhq/notion-mcp-server → 구식 자체 호스팅 항목입니다. 제거하세요
그다음 Claude에게 실제 작업을 하나 시켜 보세요:
Find the Notion page for our next feature, list the requirements that don't have a matching file in this repo yet, and don't edit anything in NotionClaude가 notion-search를 호출한 다음 notion-fetch를 호출하고, 페이지를 코드와 비교한다면 연결과 권한이 제대로 작동하는 것입니다.
피해야 할 흔한 실수
- 오래된 튜토리얼을 따르기. 내부 통합을 만들고,
ntn_토큰을 복사하고, 각 페이지를 그 통합과 공유하라고 안내하는 가이드는 자체 호스팅 서버용입니다. 호스팅 서버에서는 그런 작업이 전혀 필요하지 않습니다.
- 두 서버를 모두 유지하기. 오래된
notionApi항목이 아직 등록되어 있으면 Claude는 Notion 도구를 두 세트로 보게 됩니다.claude mcp remove notionApi로 제거하세요.
- Claude가 검토 없이 페이지를 편집하게 두기. Notion의 보안 가이드는 페이지 내용에 프롬프트 인젝션 텍스트가 들어 있을 수 있다고 경고합니다. Notion 쓰기 도구에 대해서는 Claude Code의 권한 프롬프트를 켜 둔 채로 유지하고, 바꾸려는 내용을 읽어 보세요.
- 검색을 과도하게 남발하기.
notion-search는 분당 30회로 제한됩니다. 속도 제한 오류가 발생하면 Claude에게 병렬 검색 수를 줄이도록 요청하세요.
- 잘못된 워크스페이스로 로그인하기. OAuth 페이지에서 워크스페이스를 선택할 수 있습니다. 검색 결과가 비어 있으면
claude mcp logout notion을 실행한 뒤 올바른 워크스페이스로 다시 로그인하세요.
Q&A
무료인가요?
이 서버는 어떤 Notion 요금제에서든 무료로 연결할 수 있습니다. 연결된 앱 전반의 AI 검색이나 특정 검색 필터 같은 일부 기능은 Notion 요금제에 따라 달라집니다.
Claude가 내 전체 워크스페이스를 볼 수 있나요?
Claude는 사용자의 Notion 계정이 볼 수 있는 것만 볼 수 있고, 그 이상은 볼 수 없습니다. 범위를 더 엄격하게 제한하려면 Claude가 필요로 하는 팀스페이스에만 접근할 수 있는 계정으로 로그인하세요.
아직 npm 패키지가 필요한가요?
아니요. 호스팅 서버가 그 역할을 대신합니다. Notion에 따르면 자체 호스팅 저장소는 종료될 수 있으며, 그곳의 이슈는 적극적으로 모니터링되지 않습니다.
우리 팀도 이 설정을 공유할 수 있나요?
네. --scope project로 추가하고 생성된 .mcp.json을 커밋하세요. 다만 각자는 여전히 자신의 Notion 계정으로 로그인해야 합니다.
어떻게 제거하나요?
claude mcp remove notion --scope user. Notion 쪽 승인도 함께 철회하려면 Notion의 Settings → Connections에서 연결을 제거하세요.
공식 자료
- Notion MCP 연결하기 — Claude Code 및 다른 클라이언트를 위한 공식 설정 안내
- Notion MCP 지원 도구 — 모든 도구, 요금제 제한, 속도 제한
- Notion MCP 보안 모범 사례 — 프롬프트 인젝션과 관리자 제어
- Claude Code MCP 문서 — scope, OAuth,
claude mcp명령어
원문은 quickpromptco.com에 처음 게시되었으며, 이 가이드는 그곳에서 최신 상태로 유지됩니다.
출처
- 원문: https://dev.to/juholee/notion-mcp-for-claude-code-the-official-hosted-server-in-1-command-no-api-token-3ba (2026-10-14 · quickpromptco)