본문으로 건너뛰기
MCP 서버 전체 목록

Notion MCP Server

  • 추천0
  • GitHub 별4.7K
  • 생산성라이선스MIT

Notion API용 MCP 서버. AI 에이전트가 Notion 페이지 · 데이터 소스를 검색 · 읽기 · 쓰기 하게 해 줘요. MIT

원본:makenotion/notion-mcp-server

설치 방법은 설치 탭에 정리했어요.

설명

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-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개).


페이지 내용을 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 통합 토큰 만들기

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

예를 들어 "Configuration" 탭에서 "Read content" 권한만 주면 읽기 전용 통합 토큰을 만들 수 있습니다.

"Read content"만 체크된 Notion 통합 토큰 권한

2. 통합에 내용 연결하기

쓸 페이지와 데이터베이스가 통합에 연결되어 있는지 확인하세요.

내부 통합 설정의 Access 탭으로 가서 접근 권한을 편집하고 쓰려는 페이지를 고르세요.

통합 Access 탭

통합 접근 권한 편집

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

Notion 연결에 통합 토큰 추가하기

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 탭에서 찾을 수 있습니다.

개발자 포털의 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

연결마다 토큰을 정하는 순서는 다음과 같습니다.

  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

저장소

makenotion/notion-mcp-server