Notion MCP 서버
Notion API용 MCP 서버로, LLM이 Notion 작업 공간과 상호 작용할 수 있도록 지원합니다. 또한, 마크다운 변환을 사용하여 LLM과 통신할 때 컨텍스트 크기를 줄이고 토큰 사용을 최적화하며 상호 작용의 효율성을 높입니다.
설정
위에서 언급한 단계에 대한 자세한 설명은 다음 문서에서 확인할 수 있습니다.
Notion 통합 만들기 :
Notion 통합 페이지를 방문하세요.
"새로운 통합"을 클릭합니다.
통합의 이름을 지정하고 적절한 권한을 선택합니다(예: "콘텐츠 읽기", "콘텐츠 업데이트").
비밀 키를 검색하세요 :
통합에서 "내부 통합 토큰"을 복사합니다.
이 토큰은 인증에 사용됩니다.
작업 공간에 통합 추가 :
Notion에서 통합에 액세스하려는 페이지나 데이터베이스를 엽니다.
오른쪽 상단의 "···" 버튼을 클릭하세요.
"연결" 버튼을 클릭하고 위의 1단계에서 만든 통합을 선택하세요.
Claude Desktop 구성 :
claude_desktop_config.json에 다음을 추가합니다.
지엑스피1
또는
Related MCP server: SystemPrompt MCP Notion Server
환경 변수
NOTION_API_TOKEN(필수): Notion API 통합 토큰입니다.NOTION_MARKDOWN_CONVERSION: 실험적인 마크다운 변환을 활성화하려면 "true"로 설정합니다. 이렇게 하면 콘텐츠를 볼 때 토큰 사용량을 크게 줄일 수 있지만, 페이지 콘텐츠를 편집할 때 문제가 발생할 수 있습니다.
명령줄 인수
--enabledTools: 활성화할 도구 목록을 쉼표로 구분하여 표시합니다(예: "notion_retrieve_page, notion_query_database"). 지정된 경우 나열된 도구만 사용할 수 있습니다. 지정하지 않으면 모든 도구가 활성화됩니다.
읽기 전용 도구 예(복사-붙여넣기 가능):
고급 구성
마크다운 변환
기본적으로 모든 응답은 JSON 형식으로 반환됩니다. 토큰 소모를 줄이기 위해 실험적인 마크다운 변환을 활성화할 수 있습니다.
또는
NOTION_MARKDOWN_CONVERSION "true" 로 설정하면 응답이 마크다운 형식으로 변환됩니다( format 매개변수가 "markdown" 으로 설정된 경우). 따라서 사람이 읽기 쉽고 토큰 사용량이 크게 줄어듭니다. 하지만 이 기능은 실험 단계이므로 페이지 콘텐츠를 편집할 때 변환 과정에서 원본 구조가 손실되어 문제가 발생할 수 있습니다.
도구 호출에서 format 매개변수를 "json" 또는 "markdown" 으로 설정하여 요청별로 형식을 제어할 수 있습니다.
콘텐츠만 볼 때 가독성을 높이려면
"markdown"사용하세요.반환된 콘텐츠를 수정해야 하는 경우
"json"사용하세요.
문제 해결
권한 오류가 발생하는 경우:
통합에 필요한 권한이 있는지 확인하세요.
관련 페이지나 데이터베이스에 통합이 초대되었는지 확인하세요.
claude_desktop_config.json에 토큰과 구성이 올바르게 설정되었는지 확인하세요.
프로젝트 구조
이 프로젝트는 유지 관리성과 가독성을 개선하기 위해 모듈 방식으로 구성됩니다.
디렉토리 설명
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 파일을 참조하세요.