Notion MCP

npx add-mcp 'https://mcp.notion.com/mcp'

Notion MCP 서버

[!NOTE]

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

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

기능	Remote Notion MCP	이 프로젝트(로컬)
빠르고 호스팅된 경험	✅	로컬에서 실행 및 업데이트
토큰 효율적인 응답	✅	제한적
AI 에이전트에 맞춤화된 강력한 도구	✅	기본 API 파생 도구
Notion 워크스페이스 전체의 의미적 검색	✅	키워드 검색만 가능
연결된 앱 전반의 AI 커넥터 검색	✅	사용 불가
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에 노출하면 워크스페이스 데이터에 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_****를 통합 시크릿으로 바꾸는 것을 잊지 마세요. 통합 구성 탭에서 찾을 수 있습니다:

전송 옵션

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 인증 비활성화

명시적인 안전하지 않은 플래그로만 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 통합에 고정됩니다. 단일 배포가 여러 통합을 제공하도록 하려면 각 클라이언트가 연결별로 자체 Notion 통합 토큰을 제공하도록 토큰 전달을 활성화하세요:

# Enable per-request Notion tokens (flag or ENABLE_TOKEN_PASSTHROUGH=true)
npx @notionhq/notion-mcp-server --transport http --enable-token-passthrough

그런 다음 클라이언트는 전용 Notion-Token 헤더를 사용하여 initialize 요청에 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

각 연결에 대한 토큰 해석 방식(순서대로):

1. Notion-Token 헤더(권장 — 명확하며 서버 자체 Authorization 게이트웨이 인증과 함께 작동). 있는 경우 유효한 Notion 토큰이어야 하며, 그렇지 않으면 요청이 401로 거부됩니다.
2. Authorization: Bearer ntn_**** — 서버 자체 bearer 인증이 꺼진 경우에만(--unsafe-disable-auth), 헤더가 Notion 토큰을 직접 전달할 수 있습니다.
3. 그 외에는 시작 환경 토큰(NOTION_TOKEN / OPENAPI_MCP_HEADERS)이 설정된 경우 이를 사용하므로 전달과 기본 통합이 한 배포에서 공존할 수 있습니다.

참고:

• Notion 토큰 접두사(ntn_, 레거시 secret_)가 있는 값만 Notion 토큰으로 처리되므로 서버의 게이트웨이 시크릿과 테넌트의 Notion 토큰이 충돌하지 않습니다.
• 각 토큰은 해당 MCP 세션에 바인딩됩니다. 토큰은 기록되지 않습니다(수정된 접두사만 출력됨).
• 이는 의도적인 토큰 전달 설정입니다. 항상 TLS를 통해 배포하고, 멀티 테넌트 트래픽 앞의 게이트웨이로 서버 자체 bearer 인증(--auth-token)을 활성화된 상태로 유지하는 것이 좋습니다.

예시

1. 다음 지침 사용

Comment "Hello MCP" on page "Getting started"

AI는 작업을 달성하기 위해 v1/search 및 v1/comments 두 API 호출을 올바르게 계획합니다.

1. 마찬가지로 다음 지침은 "Development" 상위 페이지에 "Notion MCP"라는 새 페이지를 추가합니다.

Add a page titled "Notion MCP" to page "Development"

1. 콘텐츠 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에서 변경 사항을 로컬로 테스트하기:

1. 저장소 루트에서 npm link 명령을 실행하여 notion-mcp-server 패키지에 대한 머신 전역 심볼릭 링크를 생성합니다.
2. 아래 구성 스니펫을 Cursor의 mcp.json (또는 테스트하려는 다른 MCP 클라이언트)에 병합합니다.
3. (정리) 저장소 루트에서 npm unlink을 실행합니다.

{
  "mcpServers": {
    "notion-local-package": {
      "command": "notion-mcp-server",
      "env": {
        "NOTION_TOKEN": "ntn_..."
      }
    }
  }
}

게시

npm login
npm publish --access public