Notion MCP 서버

Notion API용 MCP 서버로, LLM이 Notion 작업 공간과 상호 작용할 수 있도록 지원합니다. 또한, 마크다운 변환을 사용하여 LLM과 통신할 때 컨텍스트 크기를 줄이고 토큰 사용을 최적화하며 상호 작용의 효율성을 높입니다.

설정

위에서 언급한 단계에 대한 자세한 설명은 다음 문서에서 확인할 수 있습니다.

영어 버전: https://dev.to/suekou/operating-notion-via-claude-desktop-using-mcp-c0h
일본어 버전: https://qiita.com/suekou/items/44c864583f5e3e6325d9

Notion 통합 만들기 :
- Notion 통합 페이지를 방문하세요.
- "새로운 통합"을 클릭합니다.
- 통합의 이름을 지정하고 적절한 권한을 선택합니다(예: "콘텐츠 읽기", "콘텐츠 업데이트").
비밀 키를 검색하세요 :
- 통합에서 "내부 통합 토큰"을 복사합니다.
- 이 토큰은 인증에 사용됩니다.
작업 공간에 통합 추가 :
- Notion에서 통합에 액세스하려는 페이지나 데이터베이스를 엽니다.
- 오른쪽 상단의 "···" 버튼을 클릭하세요.
- "연결" 버튼을 클릭하고 위의 1단계에서 만든 통합을 선택하세요.
Claude Desktop 구성 : claude_desktop_config.json 에 다음을 추가합니다.

지엑스피1

또는

{
  "mcpServers": {
    "notion": {
      "command": "node",
      "args": ["your-built-file-path"],
      "env": {
        "NOTION_API_TOKEN": "your-integration-token"
      }
    }
  }
}

환경 변수

NOTION_API_TOKEN (필수): Notion API 통합 토큰입니다.
NOTION_MARKDOWN_CONVERSION : 실험적인 마크다운 변환을 활성화하려면 "true"로 설정합니다. 이렇게 하면 콘텐츠를 볼 때 토큰 사용량을 크게 줄일 수 있지만, 페이지 콘텐츠를 편집할 때 문제가 발생할 수 있습니다.

명령줄 인수

--enabledTools : 활성화할 도구 목록을 쉼표로 구분하여 표시합니다(예: "notion_retrieve_page, notion_query_database"). 지정된 경우 나열된 도구만 사용할 수 있습니다. 지정하지 않으면 모든 도구가 활성화됩니다.

읽기 전용 도구 예(복사-붙여넣기 가능):

node build/index.js --enabledTools=notion_retrieve_block,notion_retrieve_block_children,notion_retrieve_page,notion_query_database,notion_retrieve_database,notion_search,notion_list_all_users,notion_retrieve_user,notion_retrieve_bot_user,notion_retrieve_comments

고급 구성

마크다운 변환

기본적으로 모든 응답은 JSON 형식으로 반환됩니다. 토큰 소모를 줄이기 위해 실험적인 마크다운 변환을 활성화할 수 있습니다.

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@suekou/mcp-notion-server"],
      "env": {
        "NOTION_API_TOKEN": "your-integration-token",
        "NOTION_MARKDOWN_CONVERSION": "true"
      }
    }
  }
}

또는

{
  "mcpServers": {
    "notion": {
      "command": "node",
      "args": ["your-built-file-path"],
      "env": {
        "NOTION_API_TOKEN": "your-integration-token",
        "NOTION_MARKDOWN_CONVERSION": "true"
      }
    }
  }
}

NOTION_MARKDOWN_CONVERSION "true" 로 설정하면 응답이 마크다운 형식으로 변환됩니다( format 매개변수가 "markdown" 으로 설정된 경우). 따라서 사람이 읽기 쉽고 토큰 사용량이 크게 줄어듭니다. 하지만 이 기능은 실험 단계이므로 페이지 콘텐츠를 편집할 때 변환 과정에서 원본 구조가 손실되어 문제가 발생할 수 있습니다.

도구 호출에서 format 매개변수를 "json" 또는 "markdown" 으로 설정하여 요청별로 형식을 제어할 수 있습니다.

콘텐츠만 볼 때 가독성을 높이려면 "markdown" 사용하세요.
반환된 콘텐츠를 수정해야 하는 경우 "json" 사용하세요.

문제 해결

권한 오류가 발생하는 경우:

통합에 필요한 권한이 있는지 확인하세요.
관련 페이지나 데이터베이스에 통합이 초대되었는지 확인하세요.
claude_desktop_config.json 에 토큰과 구성이 올바르게 설정되었는지 확인하세요.

프로젝트 구조

이 프로젝트는 유지 관리성과 가독성을 개선하기 위해 모듈 방식으로 구성됩니다.

./
├── src/
│   ├── index.ts              # Entry point and command-line handling
│   ├── client/
│   │   └── index.ts          # NotionClientWrapper class for API interactions
│   ├── server/
│   │   └── index.ts          # MCP server setup and request handling
│   ├── types/
│   │   ├── index.ts          # Type exports
│   │   ├── args.ts           # Tool argument interfaces
│   │   ├── common.ts         # Common schema definitions
│   │   ├── responses.ts      # API response type definitions
│   │   └── schemas.ts        # Tool schema definitions
│   ├── utils/
│   │   └── index.ts          # Utility functions
│   └── markdown/
│       └── index.ts          # Markdown conversion utilities

디렉토리 설명

index.ts : 애플리케이션 진입점. 명령줄 인수를 구문 분석하고 서버를 시작합니다.
client/ : Notion API와 통신을 담당하는 모듈입니다.
- index.ts : NotionClientWrapper 클래스는 모든 API 호출을 구현합니다.
server/ : MCP 서버 구현.
- index.ts : Claude로부터 받은 요청을 처리하고 적절한 클라이언트 메서드를 호출합니다.
types/ : 유형 정의 모듈.
- index.ts : 모든 유형을 내보냅니다.
- args.ts : 도구 인수에 대한 인터페이스 정의.
- common.ts : 일반적인 스키마(ID 형식, 서식 있는 텍스트 등)에 대한 정의입니다.
- responses.ts : Notion API 응답에 대한 유형 정의입니다.
- schemas.ts : MCP 도구 스키마에 대한 정의입니다.
utils/ : 유틸리티 함수.
- index.ts : 필터링이 가능한 도구와 같은 기능입니다.
markdown/ : 마크다운 변환 기능.
- index.ts : JSON 응답을 Markdown 형식으로 변환하기 위한 로직입니다.

도구

모든 도구는 다음과 같은 선택적 매개변수를 지원합니다.

format (문자열, "json" 또는 "markdown", 기본값: "markdown"): 응답 형식을 제어합니다. 사람이 읽을 수 있는 출력에는 "markdown"을 사용하고, 프로그래밍 방식으로 원본 데이터 구조에 접근하려면 "json"을 사용합니다. 참고: 마크다운 변환은 NOTION_MARKDOWN_CONVERSION 환경 변수가 "true"로 설정된 경우에만 작동합니다.

notion_append_block_children
- 부모 블록에 자식 블록을 추가합니다.
- 필수 입력 사항:
  - block_id (문자열): 부모 블록의 ID입니다.
  - children (배열): 추가할 블록 객체의 배열입니다.
- 반환: 추가된 블록에 대한 정보.
notion_retrieve_block
- 특정 블록에 대한 정보를 검색합니다.
- 필수 입력 사항:
  - block_id (문자열): 검색할 블록의 ID입니다.
- 반환: 블록에 대한 자세한 정보입니다.
notion_retrieve_block_children
- 특정 블록의 자식을 검색합니다.
- 필수 입력 사항:
  - block_id (문자열): 부모 블록의 ID입니다.
- 선택 입력 사항:
  - start_cursor (문자열): 다음 페이지 결과에 대한 커서입니다.
  - page_size (숫자, 기본값: 100, 최대: 100): 검색할 블록 수.
- 반환: 자식 블록 목록.
notion_delete_block
- 특정 블록을 삭제합니다.
- 필수 입력 사항:
  - block_id (문자열): 삭제할 블록의 ID입니다.
- 반환: 삭제 확인.
notion_retrieve_page
- 특정 페이지에 대한 정보를 검색합니다.
- 필수 입력 사항:
  - page_id (문자열): 검색할 페이지의 ID입니다.
- 반환: 페이지에 대한 자세한 정보.
notion_update_page_properties
- 페이지의 속성을 업데이트합니다.
- 필수 입력 사항:
  - page_id (문자열): 업데이트할 페이지의 ID입니다.
  - properties (객체): 업데이트할 속성입니다.
- 반환: 업데이트된 페이지에 대한 정보.
notion_create_database
- 새로운 데이터베이스를 만듭니다.
- 필수 입력 사항:
  - parent (객체): 데이터베이스의 부모 객체입니다.
  - properties (객체): 데이터베이스의 속성 스키마.
- 선택 입력 사항:
  - title (배열): 데이터베이스의 제목을 서식 있는 텍스트 배열로 나타냅니다.
- 반환: 생성된 데이터베이스에 대한 정보입니다.
notion_query_database
- 데이터베이스를 쿼리합니다.
- 필수 입력 사항:
  - database_id (문자열): 쿼리할 데이터베이스의 ID입니다.
- 선택 입력 사항:
  - filter (객체): 필터 조건.
  - sorts (배열): 정렬 조건.
  - start_cursor (문자열): 다음 페이지 결과에 대한 커서입니다.
  - page_size (숫자, 기본값: 100, 최대: 100): 검색할 결과 수.
- 반환값: 쿼리의 결과 목록입니다.
notion_retrieve_database
- 특정 데이터베이스에 대한 정보를 검색합니다.
- 필수 입력 사항:
  - database_id (문자열): 검색할 데이터베이스의 ID입니다.
- 반환: 데이터베이스에 대한 자세한 정보.
notion_update_database

데이터베이스에 대한 정보를 업데이트합니다.
필수 입력 사항:
- database_id (문자열): 업데이트할 데이터베이스의 ID입니다.
선택 입력 사항:
- title (배열): 데이터베이스의 새 제목입니다.
- description (배열): 데이터베이스에 대한 새로운 설명입니다.
- properties (객체): 업데이트된 속성 스키마.
반환: 업데이트된 데이터베이스에 대한 정보입니다.

notion_create_database_item

Notion 데이터베이스에 새로운 항목을 만듭니다.
필수 입력 사항:
- database_id (문자열): 항목을 추가할 데이터베이스의 ID입니다.
- properties (객체): 새 항목의 속성입니다. 이 속성은 데이터베이스 스키마와 일치해야 합니다.
반환: 새로 생성된 항목에 대한 정보입니다.

notion_search

제목으로 페이지나 데이터베이스를 검색합니다.
선택 입력 사항:
- query (문자열): 페이지나 데이터베이스 제목에서 검색할 텍스트입니다.
- filter (객체): 결과를 페이지 또는 데이터베이스로만 제한하는 기준입니다.
- sort (객체): 결과를 정렬하는 기준
- start_cursor (문자열): 페이지 시작 커서.
- page_size (숫자, 기본값: 100, 최대: 100): 검색할 결과 수.
반환: 일치하는 페이지 또는 데이터베이스 목록입니다.

notion_list_all_users

Notion 작업 공간에 있는 모든 사용자를 나열합니다.
참고: 이 기능을 사용하려면 Notion Enterprise 플랜으로 업그레이드하고 조직 API 키를 사용해야 권한 오류가 방지됩니다.
선택 입력 사항:
- start_cursor(문자열): 사용자 목록을 나열하기 위한 페이지 시작 커서입니다.
- page_size(숫자, 최대: 100): 검색할 사용자 수.
반환값: 작업 공간에 있는 모든 사용자의 페이지가 매겨진 목록입니다.

notion_retrieve_user

Notion에서 user_id로 특정 사용자를 검색합니다.
참고: 이 기능을 사용하려면 Notion Enterprise 플랜으로 업그레이드하고 조직 API 키를 사용해야 권한 오류가 방지됩니다.
필수 입력 사항:
- user_id(문자열): 검색할 사용자의 ID입니다.
반환값: 지정된 사용자에 대한 자세한 정보.

notion_retrieve_bot_user

Notion에서 현재 토큰과 연결된 봇 사용자를 검색합니다.
반환: 통합을 승인한 사람의 세부 정보를 포함하여 봇 사용자에 대한 정보입니다.

notion_create_comment

Notion에서 댓글을 작성하세요.
통합에는 '댓글 삽입' 기능이 필요합니다.
page_id 또는 discussion_id 하나를 사용하여 parent 객체를 지정하지만, 둘 다 지정할 수는 없습니다.
필수 입력 사항:
- rich_text (배열): 댓글 내용을 나타내는 서식 있는 텍스트 개체의 배열입니다.
선택 입력 사항:
- parent (객체): page_id 사용하는 경우 반드시 포함해야 합니다.
- discussion_id (문자열): 기존 토론 스레드 ID입니다.
반환: 생성된 댓글에 대한 정보입니다.

notion_retrieve_comments

Notion 페이지나 블록에서 해결되지 않은 댓글 목록을 검색합니다.
통합에는 '댓글 읽기' 기능이 필요합니다.
필수 입력 사항:
- block_id (문자열): 댓글을 검색하려는 블록이나 페이지의 ID입니다.
선택 입력 사항:
- start_cursor (문자열): 페이지 시작 커서.
- page_size (숫자, 최대: 100): 검색할 댓글 수.
반환값: 지정된 블록이나 페이지와 연관된 댓글의 페이지별 목록입니다.

특허

이 MCP 서버는 MIT 라이선스에 따라 라이선스가 부여됩니다. 즉, MIT 라이선스의 약관에 따라 소프트웨어를 자유롭게 사용, 수정 및 배포할 수 있습니다. 자세한 내용은 프로젝트 저장소의 LICENSE 파일을 참조하세요.

Notion MCP Server

Integrations