notion-mcp-server

Notion MCP Server
참고

최상의 경험을 위해 공식 호스팅 MCP 서버인 Remote Notion MCP 를 사용하세요. 이 저장소는 더 이상 적극적으로 유지 관리되거나 지원되지 않는 별도의 자체 호스팅 MCP 서버 구현입니다. 대신 Remote Notion MCP를 사용하시기 바랍니다. Remote Notion MCP는 훨씬 적은 토큰으로 AI 에이전트에게 더 빠른 결과를 제공하도록 특별히 설계되었습니다.

Remote Notion MCP는 워크스페이스와 연결된 앱을 시맨틱하게 검색하고, Markdown으로 페이지를 읽고 편집하며, 가장 관련성 높은 컨텍스트만 반환할 수 있습니다. 즉, 대기 시간이 줄어들고, 컨텍스트 윈도우 사용량이 감소하며, 토큰 비용이 낮아집니다. 또한 OAuth를 사용하고 각 사용자의 기존 Notion 권한을 자동으로 준수합니다—API 토큰, JSON 구성, 수동 페이지 공유, 유지 관리할 로컬 서버가 필요하지 않습니다.

기능
Remote Notion MCP
이 프로젝트 (로컬)

빠른 호스팅 경험
✅
로컬에서 실행 및 업데이트

토큰 효율적인 응답
✅
제한적

AI 에이전트에 맞춰진 강력한 도구
✅
기본 API 기반 도구

Notion 워크스페이스 전반의 시맨틱 검색
✅
키워드 검색만 가능

연결된 앱 전반의 AI Connector 검색
✅
사용 불가

Markdown 기반 페이지 읽기 및 편집
✅
두 개의 페이지 콘텐츠 도구로 제한

간편한 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이 필요합니다. 이제 서버는 OpenAPI 사양에서 작업별로 Notion-Version 헤더를 가져오므로, 이 도구들은 2026-03-11을 사용하는 반면 나머지 API는 계속 2025-09-03을 사용합니다—구성이 필요하지 않습니다. OPENAPI_MCP_HEADERS를 통해 Notion-Version을 직접 설정하면 모든 도구에 대해 해당 값이 우선합니다.

설치
1. Notion에서 통합 설정
https://www.notion.so/profile/integrations 로 이동하여 새 내부 통합을 생성하거나 기존 통합을 선택하세요.

Notion API의 노출 범위를 제한하고 있지만(예: MCP를 통해 데이터베이스를 삭제할 수 없음), LLM에 워크스페이스 데이터를 노출함으로써 발생하는 위험이 전혀 없는 것은 아닙니다. 보안에 민감한 사용자는 통합의 기능(Capabilities) 을 추가로 구성할 수 있습니다.

예를 들어, "구성" 탭에서 "콘텐츠 읽기" 액세스만 부여하여 읽기 전용 통합 토큰을 생성할 수 있습니다:

2. 콘텐츠를 통합에 연결
관련 페이지와 데이터베이스가 통합에 연결되어 있는지 확인하세요.

이를 위해 내부 통합 설정의 액세스 탭을 방문하세요. 액세스를 편집하고 사용하려는 페이지를 선택하세요.

또는 개별적으로 페이지 액세스 권한을 부여할 수 있습니다. 대상 페이지를 방문하여 점 3개를 클릭하고 "통합에 연결"을 선택해야 합니다.

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_****를 통합 시크릿으로 바꾸는 것을 잊지 마세요. 통합 구성 탭에서 찾을 수 있습니다:

전송 옵션
Notion MCP Server는 두 가지 전송 모드를 지원합니다:

STDIO 전송 (기본값)
기본 전송 모드는 통신에 표준 입출력을 사용합니다. 이는 Claude Desktop과 같은 대부분의 클라이언트에서 사용하는 표준 MCP 전송입니다.

# 기본 stdio 전송으로 실행
npx @notionhq/notion-mcp-server

# 또는 stdio를 명시적으로 지정
npx @notionhq/notion-mcp-server --transport stdio
Streamable HTTP 전송
HTTP 통신을 선호하는 웹 기반 애플리케이션이나 클라이언트의 경우 Streamable HTTP 전송을 사용할 수 있습니다:

# 포트 3000(기본값)에서 Streamable HTTP 전송으로 실행
npx @notionhq/notion-mcp-server --transport http

# 사용자 지정 포트에서 실행
npx @notionhq/notion-mcp-server --transport http --port 8080

# 다른 호스트에 바인딩. 기본값은 127.0.0.1입니다.
npx @notionhq/notion-mcp-server --transport http --host 0.0.0.0

# 사용자 지정 인증 토큰으로 실행
npx @notionhq/notion-mcp-server --transport http --auth-token " your-secret-token "
Streamable HTTP 전송을 사용할 때 서버는 기본적으로 http://127.0.0.1:<port>/mcp 에서 사용할 수 있습니다.

인증
Streamable HTTP 전송은 보안을 위해 베어러 토큰 인증이 필요합니다. 세 가지 옵션이 있습니다:

옵션 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 인증 비활성화
명시적인 안전하지 않은 플래그를 사용해야만 베어러 토큰 인증을 비활성화할 수 있습니다:

npx @notionhq/notion-mcp-server --transport http --unsafe-disable-auth
경고: --unsafe-disable-auth는 안전하지 않습니다. 서버가 DNS 리바인딩을 통해 방문하는 페이지에 접근 가능할 수 있습니다. 격리된 네트워크에서만 사용하세요.

인증이 비활성화되면 서버는 구성된 로컬 호스트 및 루프백 호스트에 대해 Host 및 Origin 헤더를 확인하여 DNS 리바인딩 보호를 활성화합니다. 이전 --disable-auth 플래그는 여전히 더 이상 사용되지 않는 별칭으로 허용되지만 경고를 출력합니다.

HTTP 요청 만들기
Streamable HTTP 전송에 대한 모든 요청은 Authorization 헤더에 베어러 토큰을 포함해야 합니다:

# 예제 요청
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 환경 변수(권장) 또는 Notion 통합과 함께 OPENAPI_MCP_HEADERS 환경 변수를 설정해야 합니다…