원문 보기
GitHub - ccabanillas/notion-mcp: A Model Context Protocol (MCP) server implementation for Notion integration, providing a standardized interface for interacting with Notion's API.
Service

GitHub - ccabanillas/notion-mcp: A Model Context Protocol (MCP) server implementation for Notion integration, providing a standardized interface for interacting with Notion's API.

ccabanillas
2025.04.14
·GitHub·by Anonymous
#Notion API#MCP#Python#Server

핵심 포인트

  • 1Notion MCP 서버는 Notion API와의 통합을 제공하여 Claude Desktop과 같은 MCP 클라이언트에서 Notion 데이터에 표준화된 방식으로 접근하고 상호 작용할 수 있도록 합니다.
  • 2이 서버는 Notion 데이터베이스 목록 조회 및 쿼리, 페이지 생성 및 업데이트, Notion 워크스페이스 내 검색 등의 핵심 기능을 Pydantic v2 모델과 함께 비동기적으로 지원합니다.
  • 3설치는 저장소를 클론하고 가상 환경에 종속성을 설치한 후, Notion API 키를 포함하는 .env 파일을 구성하여 Notion 통합 토큰을 설정함으로써 이루어집니다.

ccabanillas/notion-mcp 프로젝트는 Notion 통합을 위한 Model Context Protocol (MCP) 서버 구현체로, Notion의 API와 상호 작용하기 위한 표준화된 인터페이스를 제공합니다. 이는 Claude Desktop 및 다른 MCP 클라이언트와 호환됩니다.

주요 기능 및 역할:
이 서버는 Notion API의 다양한 기능을 MCP 표준에 맞춰 노출합니다. 구체적인 기능은 다음과 같습니다:

  • Notion 데이터베이스를 목록화하고 쿼리할 수 있습니다.
  • Notion 페이지를 생성하고 업데이트할 수 있습니다.
  • Notion 워크스페이스 전반에 걸쳐 검색 기능을 제공합니다.
  • 데이터베이스의 세부 정보와 블록 자식(block children)을 가져올 수 있습니다.
  • httpx 라이브러리를 활용하여 완전한 async/await 지원을 통해 비동기 작업을 효율적으로 처리합니다.
  • Pydantic v2 모델을 사용하여 Notion 객체의 데이터 모델을 정의함으로써 타입 안정성을 보장합니다.
  • 상세한 로깅을 포함한 적절한 오류 처리 메커니즘을 갖추고 있습니다.
  • MCP 1.6.0 버전과 호환성을 유지합니다.

핵심 방법론 및 기술적 세부사항:
notion-mcp 서버는 Python으로 구현되었으며, Notion API와의 통신을 추상화하고 이를 MCP 표준에 맞는 메시지 형식으로 변환하는 브릿지 역할을 수행합니다.

  • 아키텍처: 프로젝트 구조는 src/notion_mcp/models/notion.py에 Notion 객체(Pydantic 모델)를 위한 데이터 모델을 정의하고, src/notion_mcp/client.py에서 실제 Notion API 호출 로직을 구현합니다. src/notion_mcp/server.py는 MCP 프로토콜을 처리하고 클라이언트 요청을 Notion API 호출로 매핑하며, client.py를 통해 Notion과 통신합니다. src/notion_mcp/__main__.py는 서버의 진입점 역할을 합니다.
  • 데이터 모델링 및 유효성 검사: Pydantic v2를 사용하여 Notion API로부터 수신되거나 Notion API로 전송되는 모든 데이터(Notion 페이지, 데이터베이스, 블록 등)의 구조를 타입 안전하게 정의합니다. 이는 데이터 일관성과 개발 편의성을 높이는 데 기여합니다.
  • 비동기 통신: httpx 라이브러리를 사용하여 Notion API와의 모든 HTTP 통신을 비동기적으로 처리합니다. 이를 통해 서버는 여러 클라이언트 요청을 동시에 처리하며 높은 처리량과 응답성을 유지할 수 있습니다.
  • 환경 설정: Notion API 키와 같은 민감한 정보는 .env 파일을 통해 안전하게 관리되며, 프로젝트 코드와 분리되어 보안을 강화합니다. 서버는 이 키를 사용하여 Notion 워크스페이스에 접근하고 필요한 권한을 얻습니다. Notion 통합 토큰은 Notion 웹사이트의 "My integrations" 페이지에서 생성하며, 해당 통합에 데이터베이스 접근 권한을 부여해야 합니다.
  • MCP 호환성: 이 프로젝트는 MCP 표준에 따라 JSON 기반의 메시지 포맷을 사용하여 클라이언트와 통신합니다. 이는 다양한 MCP 호환 클라이언트가 이 서버와 연동될 수 있도록 보장합니다.

설치 및 사용:

  • Smithery를 통한 자동 설치: npx -y @smithery/cli install @ccabanillas/notion-mcp --client claude 명령을 통해 Claude Desktop과 같은 클라이언트를 위해 자동으로 설치 및 구성할 수 있습니다.
  • 수동 설치: git clone으로 저장소를 복제한 후, uv 또는 표준 venv를 사용하여 가상 환경을 설정하고 uv pip install -e . 또는 pip install -e . 명령으로 의존성을 설치합니다.
  • 구성: 프로젝트 루트에 .env 파일을 생성하고 NOTIONAPIKEY=yournotionintegrationtokenNOTION_API_KEY=your_notion_integration_token 형식으로 Notion API 키를 추가해야 합니다. 또한, Notion에서 해당 통합에 데이터베이스 접근 권한을 부여해야 합니다.
  • Claude Desktop과의 연동: claude_desktop_config.json 파일(macOS의 경우 ~/Library/Application Support/Claude/claude_desktop_config.json)을 수정하여 notion-mcp 서버의 command, args, cwd 경로를 지정하여 통합합니다.

이 서버는 MIT License에 따라 배포됩니다.