Notion MCP

공식

Notion 페이지, 데이터베이스, 워크스페이스 콘텐츠를 AI 에이전트가 검색, 읽기, 생성, 업데이트할 수 있는 공식 Notion MCP 서버입니다.

GitHub
4.5k

Notion MCP(으)로 무엇을 할 수 있나요?

  • 제목으로 페이지 또는 데이터 소스 검색 — post-search를 사용하여 작업 공간 전체에서 페이지와 데이터 소스를 이름으로 찾습니다.
  • 페이지 콘텐츠를 Markdown으로 읽기 — retrieve-page-markdown으로 페이지의 전체 콘텐츠를 검색하며, 선택적으로 회의 기록을 포함할 수 있습니다.
  • 페이지 콘텐츠를 Markdown으로 편집 — update-page-markdown을 사용하여 페이지 콘텐츠를 덮어쓰거나 찾아 바꿉니다.
  • 필터와 정렬로 데이터 소스 쿼리 — query-data-source를 통해 데이터 소스에 대해 구조화된 쿼리를 실행합니다.
  • 상위 페이지 또는 데이터 소스 내에 새 페이지 생성 — post-page로 페이지를 추가하며, page_id 또는 database_id 상위 항목을 지정합니다.
  • 페이지를 다른 상위 위치로 이동 — move-page로 페이지를 이동하여 작업 공간을 재구성합니다.

문서

Notion MCP 서버

[!NOTE]

다음과 같은 개선 사항을 갖춘 원격 MCP 서버인 Notion MCP를 소개합니다:

  • 표준 OAuth를 통한 간편한 설치. 더 이상 JSON이나 API 토큰을 만지작거릴 필요가 없습니다.
  • 마크다운으로 페이지 편집을 포함하여 AI 에이전트에 맞춰진 강력한 도구. 이 도구들은 최적화된 토큰 소비를 염두에 두고 설계되었습니다.

자세히 알아보고 시작하려면 Notion MCP 문서를 참조하세요.

우리는 Notion MCP(원격)를 우선시하며 적극적으로 지원하고 있습니다. 그 결과:

  • 향후 이 로컬 MCP 서버 저장소를 종료할 수 있습니다.
  • 여기의 이슈와 풀 리퀘스트는 적극적으로 모니터링되지 않습니다.
  • 원격 MCP와 관련된 이슈를 여기에 제출하지 말고, 대신 Notion 지원팀에 문의하십시오.

notion-mcp-sm

이 프로젝트는 Notion API를 위한 MCP 서버를 구현합니다.

mcp-demo

⚠️ 버전 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-queryquery-data-sourcedatabase_id → data_source_id
update-a-databaseupdate-a-data-sourcedatabase_id → data_source_id
create-a-databasecreate-a-data-source변경 없음 (parent.page_id 사용)

참고: retrieve-a-database은 여전히 사용 가능하며 데이터 소스 ID 목록을 포함한 데이터베이스 메타데이터를 반환합니다. 특정 데이터 소스의 스키마와 속성을 가져오려면 retrieve-a-data-source을 사용하십시오.

현재 총 도구 수: 22개 (v1.x에서는 19개였음)

마크다운으로서의 페이지 콘텐츠

서버는 블록 JSON 대신 향상된 마크다운으로 페이지 콘텐츠를 작업하기 위한 두 가지 도구를 노출하며, 이는 AI 에이전트에게 훨씬 더 토큰 효율적입니다:

  • retrieve-page-markdown — 페이지의 전체 콘텐츠를 마크다운으로 읽기 (GET /v1/pages/{page_id}/markdown). 회의록 대본을 인라인으로 포함하려면 include_transcript: true를 전달하십시오.
  • update-page-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로 이동하여 새 내부 통합을 생성하거나 기존 통합을 선택하십시오.

Creating a Notion Integration token

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

예를 들어, "구성" 탭에서 "콘텐츠 읽기" 접근 권한만 부여하여 읽기 전용 통합 토큰을 만들 수 있습니다:

Notion Integration Token Capabilities showing Read content checked

2. 통합에 콘텐츠 연결

관련 페이지와 데이터베이스가 통합에 연결되어 있는지 확인하십시오.

이를 위해 내부 통합 설정의 접근 탭을 방문하십시오. 접근을 편집하고 사용하려는 페이지를 선택하십시오.

Integration Access tab

Edit integration access

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

Adding Integration Token to Notion Connections

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

Copying your Integration token from the Configuration tab in the developer portal

전송 옵션

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

스트리밍 가능 HTTP 전송

웹 기반 애플리케이션이나 HTTP 통신을 선호하는 클라이언트의 경우, 스트리밍 가능 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"

스트리밍 가능 HTTP 전송을 사용할 때, 서버는 기본적으로 http://127.0.0.1:<port>/mcp에서 사용할 수 있습니다.

인증

스트리밍 가능 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 요청 만들기

스트리밍 가능 HTTP 전송에 대한 모든 요청은 Authorization 헤더에 베어러 토큰을 포함해야 합니다:

# 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 헤더를 사용하여 초기화 요청 시 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_**** — 서버 자체 베어러 인증이 꺼져 있을 때만 (--unsafe-disable-auth), 헤더가 Notion 토큰을 직접 전달할 수 있습니다.
  3. 그렇지 않으면 시작 시 환경 변수 토큰 (NOTION_TOKEN / OPENAPI_MCP_HEADERS)이 설정된 경우, 통과와 기본 통합이 하나의 배포에서 공존할 수 있습니다.

참고:

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

예제

  1. 다음 지침 사용
Comment "Hello MCP" on page "Getting started"

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

  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