Notion ReadOnly MCP Server

Notion ReadOnly MCP 서버

이 프로젝트는 Notion API에 최적화된 읽기 전용 MCP 서버를 구현하여 AI 어시스턴트가 Notion 콘텐츠를 쿼리하고 검색할 때의 성능과 효율성에 초점을 맞춥니다.

주요 개선 사항

• 읽기 전용 디자인 : 데이터 검색 작업에만 집중하여 Notion 콘텐츠에 대한 안전한 액세스를 보장합니다.
• 최소화된 도구 세트 : 노출된 Notion API 도구 수를 15개 이상에서 문서 분석에 필수적인 6개로 줄였습니다.
• 병렬 처리 : 블록 콘텐츠를 검색하기 위해 비동기 및 병렬 API 요청을 구현하여 성능을 향상시키고 응답 시간을 크게 줄였습니다.
• 확장된 데이터베이스 액세스 : 데이터베이스, 페이지 속성, 주석 검색 작업에 대한 지원이 추가되었습니다.
• AI 도우미에 최적화 : 도구 개수를 대폭 줄여 Cursor와 같은 AI 도우미의 "도구가 너무 많으면 성능이 저하될 수 있음" 문제를 해결했습니다. 이 문제는 모델에 사용할 수 있는 도구 수를 약 40개로 제한합니다.

도구 비교

이 읽기 전용 구현은 표준 Notion API 통합에 비해 훨씬 적은 도구를 노출하여 AI 어시스턴트와의 성능과 호환성을 향상시킵니다.

축소된 도구 세트는 모든 필수 기능을 제공하는 동시에 최적의 AI 어시스턴트 성능을 위해 권장되는 도구 한도 내에 머무르는 데 도움이 됩니다.

설치

1. Notion에서 통합 설정:

https://www.notion.so/profile/integrations 로 이동하여 새로운 내부 통합을 만들거나 기존 통합을 선택하세요.

Notion API의 노출 범위를 읽기 전용 작업으로 제한하고 있지만, LLM에 노출될 경우 작업 공간 데이터에 대한 위험이 존재합니다. 보안에 민감한 사용자는 통합 기능 의 추가 구성을 고려할 수 있습니다.

예를 들어, "구성" 탭에서 "콘텐츠 읽기" 액세스만 부여하여 읽기 전용 통합 토큰을 만들 수 있습니다.

2. 클라이언트에 MCP 구성 추가:

npm 사용하기:

.cursor/mcp.json 또는 claude_desktop_config.json 에 다음을 추가합니다(MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json )

지엑스피1

Docker 사용:

.cursor/mcp.json 또는 claude_desktop_config.json 에 다음을 추가하세요.

ntn_**** 통합 비밀번호로 바꾸는 것을 잊지 마세요. 통합 설정 탭에서 비밀번호를 확인하세요.

3. 통합에 콘텐츠 연결:

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

이를 위해 해당 페이지를 방문하여 3개의 점을 클릭하고 "통합에 연결"을 선택하세요.

사용 가능한 도구

이 최적화된 서버는 필수적인 읽기 전용 Notion API 도구만 노출합니다.

• API-retrieve-a-page : 페이지 정보 가져오기
• API-get-block-children : 페이지 콘텐츠 블록 가져오기(병렬 처리 포함)
• API-retrieve-a-block : 특정 블록에 대한 세부 정보 가져오기
• API-retrieve-a-database : 데이터베이스 정보 가져오기
• API-retrieve-a-comment : 페이지 또는 블록에 대한 댓글 가져오기
• API-retrieve-a-page-property : 페이지에서 특정 속성 정보를 가져옵니다.
• API-get-one-pager : 새롭게 추가된 기능! 한 번의 호출로 모든 블록, 데이터베이스 및 관련 콘텐츠가 포함된 전체 Notion 페이지를 재귀적으로 검색합니다.

이러한 7가지 필수 도구로 제한함으로써(표준 구현에서는 15개 이상) 다음이 보장됩니다.

1. 도구 수 제한이 있는 Cursor 및 Claude와 같은 AI 어시스턴트에서 더 나은 성능 제공
2. 적절한 도구를 선택하면 AI 모델의 인지 부하가 감소합니다.
3. 고려해야 할 API 옵션이 적어 응답 시간이 더 빠릅니다.
4. API 표면 영역 최소화를 통한 보안 강화

자동 콘텐츠 탐색

새로운 API-get-one-pager 도구는 여러 API 호출 없이 Notion 페이지를 탐색할 수 있는 강력한 방법을 제공합니다.

• 재귀적 검색 : 중첩된 블록을 포함한 전체 페이지 구조를 자동으로 탐색합니다.
• 병렬 처리 : 최대 성능을 위해 여러 블록과 해당 자식을 동시에 가져옵니다.
• 지능형 캐싱 : 중복 API 호출을 최소화하기 위해 검색된 데이터를 저장합니다.
• 포괄적인 콘텐츠 : 페이지, 블록, 데이터베이스, 댓글 및 자세한 속성 정보 포함
• 사용자 정의 가능한 깊이 : 세부 사항과 성능 간의 균형을 맞추기 위해 재귀 수준을 제어합니다.

One Pager 도구 사용

이러한 자동 탐색 기능은 수십 개의 별도 API 호출을 하지 않고도 Notion 페이지의 전체 내용을 이해해야 하는 AI 어시스턴트에게 특히 유용하며, 훨씬 더 빠르고 효율적인 응답을 제공합니다.

비동기 처리

서버는 대용량 Notion 문서를 처리하기 위해 고급 병렬 처리 기술을 구현합니다.

• 여러 요청이 일괄 처리되어 동시에 처리됩니다.
• 블록 자식의 경우 페이지 매김이 자동으로 처리됩니다.
• 결과는 반환되기 전에 효율적으로 집계됩니다.
• 콘솔 로깅은 응답 형식에 영향을 주지 않고 프로세스에 대한 가시성을 제공합니다.

예시

1. 다음 지침을 사용하세요.

AI는 블록 콘텐츠의 병렬 처리를 통해 효율적으로 페이지 세부 정보를 검색합니다.

2. 데이터베이스 정보 사용:

개발

짓다:

실행하다:

특허

MIT

AI 어시스턴트 성능 이점

Cursor와 Claude와 같은 최신 AI 어시스턴트는 효과적으로 처리할 수 있는 도구 수에 제한이 있습니다.

• 대부분의 모델은 총 40개 이상의 도구를 존중하지 않을 수 있습니다.
• 도구가 너무 많으면 전반적인 성능과 추론 능력이 저하될 수 있습니다.
• 복잡한 도구 세트는 응답 지연과 의사 결정의 어려움을 증가시킵니다.

이 읽기 전용 구현은 모든 필수 기능을 유지하면서 이러한 한계를 해결하기 위해 Notion API의 표면적을 의도적으로 줄였습니다. 결과는 다음과 같습니다.

• AI 어시스턴트의 더 빠르고 안정적인 응답
• Notion 콘텐츠와 상호 작용할 때 정확도가 향상되었습니다.
• 집중된 API 설계를 통해 전반적인 성능 향상