Notion MCP Server
- 추천0
- GitHub 별4.7K
- 생산성라이선스MIT
Notion API용 MCP 서버. AI 에이전트가 Notion 페이지 · 데이터 소스를 검색 · 읽기 · 쓰기 하게 해 줘요. MIT
설치 방법은 설치 탭에 정리했어요.
설명
Notion MCP 서버
💡 알림 가장 좋은 경험을 원하면 공식 호스팅 MCP 서버인 **Remote Notion MCP**를 쓰세요. 이 저장소는 따로 만든 자체 호스팅 MCP 서버 구현이며, 더는 적극적으로 관리 · 지원하지 않습니다. 대신 Remote Notion MCP를 쓰세요. Remote Notion MCP는 더 적은 토큰으로 더 빠른 결과를 내도록 만들어졌습니다.
Remote Notion MCP는 워크스페이스와 연결된 앱을 의미 기반으로 검색하고, 페이지를 Markdown으로 읽고 고치며, 가장 관련 있는 맥락만 돌려줍니다. 그래서 기다리는 시간, 컨텍스트 창 사용량, 토큰 비용이 줄어듭니다. 또 OAuth를 쓰고 각 사용자의 기존 Notion 권한을 자동으로 따르므로, API 토큰 · JSON 설정 · 페이지 수동 공유 · 직접 유지할 로컬 서버가 필요 없습니다.
기능 Remote Notion MCP 이 프로젝트(로컬) 빠른 호스팅형 경험 ✅ 로컬에서 실행하고 업데이트 토큰 효율이 좋은 응답 ✅ 제한적 AI 에이전트에 맞춘 강력한 도구 ✅ API에서 가져온 기본 도구 Notion 워크스페이스 전체 의미 기반 검색 ✅ 키워드 검색만 연결된 앱 전반의 AI 커넥터 검색 ✅ 없음 Markdown 기반 페이지 읽기 · 편집 ✅ 페이지 내용 도구 2개로 제한 매끄러운 OAuth 설정 ✅ 토큰과 JSON을 직접 설정 각 사용자의 기존 Notion 권한 준수 ✅ 통합 권한과 페이지 공유를 직접 설정 적극적인 지원과 지속적인 개선 ✅ 적극적으로 지원하지 않음 자세한 내용과 시작 방법은 Remote Notion MCP 문서를 보세요.
Remote Notion MCP에만 우선순위를 두고 적극적인 지원을 제공합니다. 그래서 다음과 같이 됩니다.
- 앞으로 이 로컬 MCP 서버 저장소를 종료할 수 있습니다.
- 여기의 이슈와 풀 리퀘스트는 적극적으로 살피지 않습니다.
- 원격 MCP에 관한 이슈는 여기에 올리지 말고 Notion 지원팀에 문의하세요.
이 프로젝트는 Notion API를 위한 MCP 서버를 구현합니다.
⚠️ 버전 2.0.0 호환성이 깨지는 변경
버전 2.0.0은 Notion API 2025-09-03으로 옮겨 갑니다. 이 버전은 데이터베이스의 기본 개념으로 데이터 소스를 도입했습니다.
바뀐 점
없어진 도구(3개):
post-database-query-query-data-source로 대체update-a-database-update-a-data-source로 대체create-a-database-create-a-data-source로 대체
새 도구(7개):
query-data-source- 필터와 정렬로 데이터 소스(데이터베이스)를 조회합니다retrieve-a-data-source- 데이터 소스의 메타데이터와 스키마를 가져옵니다update-a-data-source- 데이터 소스 속성을 고칩니다create-a-data-source- 새 데이터 소스를 만듭니다list-data-source-templates- 데이터 소스에서 쓸 수 있는 템플릿을 나열합니다move-page- 페이지를 다른 부모 위치로 옮깁니다retrieve-a-database- 데이터 소스 ID를 포함한 데이터베이스 메타데이터를 가져옵니다
매개변수 변경:
- 모든 데이터베이스 작업이
database_id대신data_source_id를 씁니다 - 검색 필터 값이
["page", "database"]에서["page", "data_source"]로 바뀌었습니다 - 페이지를 만들 때
page_id와database_id부모를 모두 지원합니다(데이터 소스용)
옮겨 가야 하나요?
코드를 바꿀 필요는 없습니다. MCP 도구는 서버가 시작될 때 자동으로 발견됩니다. v2.0.0으로 올리면 AI 클라이언트가 새 도구 이름과 매개변수를 자동으로 봅니다. 예전 데이터베이스 도구는 더는 쓸 수 없습니다.
도구 이름을 직접 적어 두었거나 예전 데이터베이스 도구를 가리키는 프롬프트가 있다면 새 데이터 소스 도구를 쓰도록 고치세요.
| 예전 도구(v1.x) | 새 도구(v2.0) | 매개변수 변경 |
|---|---|---|
post-database-query | query-data-source | database_id → data_source_id |
update-a-database | update-a-data-source | database_id → data_source_id |
create-a-database | create-a-data-source | 변경 없음(parent.page_id 사용) |
📝 참고
retrieve-a-database는 여전히 쓸 수 있고 데이터 소스 ID 목록을 포함한 데이터베이스 메타데이터를 돌려줍니다. 특정 데이터 소스의 스키마와 속성을 얻으려면retrieve-a-data-source를 쓰세요.
지금 도구는 모두 22개입니다(v1.x는 19개).
페이지 내용을 Markdown으로
서버는 블록 JSON 대신 향상된 Markdown으로 페이지 내용을 다루는 도구 두 개를 제공합니다. AI 에이전트에 훨씬 토큰 효율이 좋습니다.
retrieve-page-markdown— 페이지 전체 내용을 Markdown으로 읽습니다(GET /v1/pages/{page_id}/markdown).include_transcript: true를 주면 회의록 녹취를 함께 넣습니다.update-page-markdown— Markdown으로 페이지 내용을 고칩니다(PATCH /v1/pages/{page_id}/markdown). 페이지 전체를 덮어쓰려면replace_content를, 필요한 부분만 찾아 바꾸려면update_content를 쓰는 것이 좋습니다.
이 엔드포인트들은 Notion API 버전 2026-03-11이 필요합니다. 서버는 이제 Notion-Version 헤더를 OpenAPI 명세에서 작업마다 가져오므로, 이 도구들은 2026-03-11을, 나머지 API는 계속 2025-09-03을 씁니다 — 따로 설정할 것은 없습니다. OPENAPI_MCP_HEADERS로 Notion-Version을 직접 정하면 그 값이 모든 도구에서 우선합니다.
설치
1. Notion에서 통합 만들기
https://www.notion.so/profile/integrations에 가서 새 내부(internal) 통합을 만들거나 이미 있는 통합을 고르세요.

Notion API 중 노출하는 범위를 제한하고 있지만(예: MCP로 데이터베이스를 지울 수는 없습니다), 워크스페이스 데이터를 LLM에 노출하면 데이터가 위험해질 가능성이 0은 아닙니다. 보안이 걱정되는 사용자는 통합의 _권한(Capabilities)_을 더 줄여 설정하는 것이 좋습니다.
예를 들어 "Configuration" 탭에서 "Read content" 권한만 주면 읽기 전용 통합 토큰을 만들 수 있습니다.

2. 통합에 내용 연결하기
쓸 페이지와 데이터베이스가 통합에 연결되어 있는지 확인하세요.
내부 통합 설정의 Access 탭으로 가서 접근 권한을 편집하고 쓰려는 페이지를 고르세요.


페이지마다 따로 접근 권한을 줄 수도 있습니다. 대상 페이지에 가서 점 3개를 누르고 "Connect to integration"을 고르세요.

3. 클라이언트에 MCP 설정 추가하기
npm으로 쓰기
Cursor와 Claude
.cursor/mcp.json 또는 claude_desktop_config.json(macOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json)에 다음을 추가하세요.
방법 1: NOTION_TOKEN 쓰기(추천)
{
"mcpServers": {
"notionApi": {
"command": "npx",
"args": ["-y", "@notionhq/notion-mcp-server"],
"env": {
"NOTION_TOKEN": "ntn_****"
}
}
}
}
방법 2: OPENAPI_MCP_HEADERS 쓰기(고급 용도)
{
"mcpServers": {
"notionApi": {
"command": "npx",
"args": ["-y", "@notionhq/notion-mcp-server"],
"env": {
"OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2025-09-03\" }"
}
}
}
}
Zed
settings.json에 다음을 추가하세요.
{
"context_servers": {
"some-context-server": {
"command": {
"path": "npx",
"args": ["-y", "@notionhq/notion-mcp-server"],
"env": {
"OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2025-09-03\" }"
}
},
"settings": {}
}
}
}
GitHub Copilot CLI
Copilot CLI로 MCP 서버를 대화형으로 추가하세요.
/mcp add
또는 설정 파일 ~/.copilot/mcp-config.json을 만들거나 고쳐서 다음을 추가하세요.
{
"mcpServers": {
"notionApi": {
"command": "npx",
"args": ["-y", "@notionhq/notion-mcp-server"],
"env": {
"NOTION_TOKEN": "ntn_****"
}
}
}
}
자세한 내용은 Copilot CLI 문서를 보세요.
Docker로 쓰기
Docker로 MCP 서버를 실행하는 방법은 두 가지입니다.
방법 1: 공식 Docker Hub 이미지 쓰기
.cursor/mcp.json 또는 claude_desktop_config.json에 다음을 추가하세요.
NOTION_TOKEN 쓰기(추천):
{
"mcpServers": {
"notionApi": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e", "NOTION_TOKEN",
"mcp/notion"
],
"env": {
"NOTION_TOKEN": "ntn_****"
}
}
}
}
OPENAPI_MCP_HEADERS 쓰기(고급 용도):
{
"mcpServers": {
"notionApi": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e", "OPENAPI_MCP_HEADERS",
"mcp/notion"
],
"env": {
"OPENAPI_MCP_HEADERS": "{\"Authorization\":\"Bearer ntn_****\",\"Notion-Version\":\"2025-09-03\"}"
}
}
}
}
이 방식은 다음과 같습니다.
- 공식 Docker Hub 이미지를 씁니다
- 환경 변수로 JSON 이스케이프를 제대로 처리합니다
- 더 믿을 만한 설정 방법입니다
방법 2: Docker 이미지를 직접 빌드하기
Docker 이미지를 직접 만들어 실행할 수도 있습니다. 먼저 Docker 이미지를 빌드하세요.
docker compose build
그다음 .cursor/mcp.json 또는 claude_desktop_config.json에 다음을 추가하세요.
NOTION_TOKEN 쓰기(추천):
{
"mcpServers": {
"notionApi": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"NOTION_TOKEN=ntn_****",
"notion-mcp-server"
]
}
}
}
OPENAPI_MCP_HEADERS 쓰기(고급 용도):
{
"mcpServers": {
"notionApi": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"OPENAPI_MCP_HEADERS={\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2025-09-03\"}",
"notion-mcp-server"
]
}
}
}
ntn_****을 내 통합 시크릿으로 바꾸는 것을 잊지 마세요. 통합 설정의 Configuration 탭에서 찾을 수 있습니다.
전송 방식
Notion MCP 서버는 두 가지 전송 모드를 지원합니다.
STDIO 전송(기본)
기본 전송 모드는 표준 입출력으로 통신합니다. Claude Desktop 같은 대부분의 클라이언트가 쓰는 표준 MCP 전송입니다.
# Run with default stdio transport
npx @notionhq/notion-mcp-server
# Or explicitly specify stdio
npx @notionhq/notion-mcp-server --transport stdio
Streamable HTTP 전송
웹 기반 애플리케이션이나 HTTP 통신을 선호하는 클라이언트에는 Streamable HTTP 전송을 쓸 수 있습니다.
# Run with Streamable HTTP transport on port 3000 (default)
npx @notionhq/notion-mcp-server --transport http
# Run on a custom port
npx @notionhq/notion-mcp-server --transport http --port 8080
# Bind to a different host. The default is 127.0.0.1.
npx @notionhq/notion-mcp-server --transport http --host 0.0.0.0
# Run with a custom authentication token
npx @notionhq/notion-mcp-server --transport http --auth-token "your-secret-token"
Streamable HTTP 전송을 쓰면 서버는 기본으로 http://127.0.0.1:<port>/mcp에서 열립니다.
인증
Streamable HTTP 전송은 보안을 위해 Bearer 토큰 인증이 필요합니다. 선택지는 세 가지입니다.
방법 1: 자동 생성 토큰(개발용으로만)
npx @notionhq/notion-mcp-server --transport http
서버가 안전한 무작위 토큰을 만들어 권한을 제한한 파일에 씁니다.
Generated auth token written to: /tmp/.notion-mcp-auth-token-12345
방법 2: 명령줄로 직접 정한 토큰(운영 추천)
npx @notionhq/notion-mcp-server --transport http --auth-token "your-secret-token"
방법 3: 환경 변수로 직접 정한 토큰(운영 추천)
AUTH_TOKEN="your-secret-token" npx @notionhq/notion-mcp-server --transport http
명령줄 인자 --auth-token과 환경 변수 AUTH_TOKEN이 모두 있으면 명령줄 인자가 우선합니다.
안전하지 않은 옵션: HTTP 인증 끄기
명시적인 unsafe 플래그로만 Bearer 토큰 인증을 끌 수 있습니다.
npx @notionhq/notion-mcp-server --transport http --unsafe-disable-auth
경고: --unsafe-disable-auth는 안전하지 않습니다. 방문한 페이지를 통해 DNS 리바인딩으로 서버에 닿을 수 있습니다. 격리된 네트워크에서만 쓰세요.
인증을 끄면 서버는 Host와 Origin 헤더를 설정된 로컬 호스트와 루프백 호스트에 대조해 DNS 리바인딩 보호를 켭니다. 예전 --disable-auth 플래그도 더 이상 권장하지 않는 별칭으로 아직 받아들이지만 경고를 출력합니다.
HTTP 요청 보내기
Streamable HTTP 전송으로 가는 모든 요청에는 Authorization 헤더에 Bearer 토큰이 들어 있어야 합니다.
# Example request
curl -H "Authorization: Bearer your-token-here" \
-H "Content-Type: application/json" \
-H "mcp-session-id: your-session-id" \
-d '{"jsonrpc": "2.0", "method": "initialize", "params": {}, "id": 1}' \
http://localhost:3000/mcp
참고: 어느 전송 모드를 쓰든 NOTION_TOKEN 환경 변수(추천) 또는 OPENAPI_MCP_HEADERS 환경 변수에 Notion 통합 토큰을 꼭 정하세요.
여러 통합 처리하기(요청마다 토큰 전달)
기본적으로 서버는 시작할 때 박아 둔 토큰 하나로 Notion에 인증하므로, 배포 하나가 Notion 통합 하나에 묶입니다. 배포 하나로 여러 통합을 처리하려면 토큰 전달(passthrough)을 켜서 각 클라이언트가 연결마다 자기 Notion 통합 토큰을 보내게 하세요.
# Enable per-request Notion tokens (flag or ENABLE_TOKEN_PASSTHROUGH=true)
npx @notionhq/notion-mcp-server --transport http --enable-token-passthrough
그러면 클라이언트는 initialize 요청에 전용 Notion-Token 헤더로 Notion 토큰을 보냅니다.
curl -H "Authorization: Bearer <server-auth-token>" \
-H "Notion-Token: ntn_****" \
-H "Content-Type: application/json" \
-d '{"jsonrpc": "2.0", "method": "initialize", "params": {}, "id": 1}' \
http://localhost:3000/mcp
연결마다 토큰을 정하는 순서는 다음과 같습니다.
Notion-Token헤더(권장 — 모호하지 않고 서버 자체의Authorization게이트웨이 인증과 함께 쓸 수 있음). 있으면 유효한 Notion 토큰이어야 하며, 아니면 요청이401로 거부됩니다.Authorization: Bearer ntn_****— 서버 자체 Bearer 인증이 꺼져 있을 때(--unsafe-disable-auth)만 쓰이며, 이때 헤더가 비어 있어 Notion 토큰을 바로 실을 수 있습니다.- 그 밖에는 시작할 때 정한 환경 변수 토큰(
NOTION_TOKEN/OPENAPI_MCP_HEADERS)이 있으면 그것을 씁니다. 그래서 토큰 전달과 기본 통합이 한 배포에 함께 있을 수 있습니다.
참고:
- Notion 토큰 접두사(
ntn_, 예전secret_)가 붙은 값만 Notion 토큰으로 취급하므로, 서버의 게이트웨이 비밀값과 사용자의 Notion 토큰이 겹치지 않습니다. - 토큰은 MCP 세션마다 묶이며, 로그에는 남지 않고(가려진 앞부분만 출력) 기록됩니다.
- 이것은 의도적으로 토큰을 전달하는 구성입니다. 항상 TLS 위에 배포하고, 여러 사용자의 트래픽 앞에서는 서버 자체의 Bearer 인증(
--auth-token)을 게이트웨이로 켜 두는 것이 좋습니다.
예시
- 다음 지시를 쓰면
Comment "Hello MCP" on page "Getting started"
AI가 v1/search와 v1/comments 두 API 호출을 알맞게 계획해 작업을 해냅니다.
- 비슷하게, 다음 지시는 "Development" 부모 페이지 아래에 "Notion MCP"라는 새 페이지를 추가합니다.
Add a page titled "Notion MCP" to page "Development"
- 내용 ID를 직접 가리킬 수도 있습니다.
Get the content of page 1a6b35e6e67f802fa7e1d27686f017f2
개발
빌드와 테스트
npm run build
npm test
실행
npx -y --prefix /path/to/local/notion-mcp-server @notionhq/notion-mcp-server
Cursor에서 변경 내용을 로컬로 시험하려면:
- 저장소 루트에서
npm link명령을 실행해notion-mcp-server패키지로 가는 컴퓨터 전역 심볼릭 링크를 만듭니다. - 아래 설정 조각을 Cursor의
mcp.json(또는 시험하려는 다른 MCP 클라이언트)에 합칩니다. - (정리) 저장소 루트에서
npm unlink를 실행합니다.
{
"mcpServers": {
"notion-local-package": {
"command": "notion-mcp-server",
"env": {
"NOTION_TOKEN": "ntn_..."
}
}
}
}
배포
npm login
npm publish --access public