Notion Local MCP

Notion 데스크탑 앱의 로컬 SQLite 캐시를 읽어 Claude에서 빠르게 Notion 문서를 검색하고 조회하는 MCP 서버입니다.

빠른 시작 (Quick Start)

1. 필수 조건

• Node.js 18+ 설치
• Notion 데스크탑 앱 설치 및 로그인

2. 자동 설정

터미널에서 아래 명령어를 실행하면 자동으로 설정됩니다:

npx @lulee/notion-local-mcp setup

🔧 Notion Local MCP Setup
========================================

🔍 Operating system: macOS
✅ Notion found: /Users/user/Library/Application Support/Notion/notion.db

Which apps do you want to configure?

  1. Claude Desktop Chat
  2. Claude Code (CLI)
  3. Both (recommended)

Enter choice [1-3, default: 3]: 3

========================================

✅ Claude Desktop: Successfully configured notion-local for Claude Desktop
✅ Claude Code: Successfully configured notion-local for Claude Code

🎉 Setup complete!

Please restart your Claude app to apply the changes.

3. 앱 재시작

Claude Desktop 또는 Claude Code를 재시작하면 사용할 수 있습니다.

끝!

---

Notion API MCP vs notion-local

	Notion API MCP	notion-local
동작 방식	Notion 서버 API 호출	로컬 SQLite 직접 읽기
Notion AI	사용 (시맨틱 검색)	사용 안 함
속도	느림 (네트워크)	빠름 (로컬)
오프라인	불가능	가능
Rate Limit	있음	없음
데이터 최신성	실시간	Notion 앱 동기화 시점
쓰기 기능	있음	없음 (읽기 전용)

권장 사용법:

• 검색/조회 → notion-local (빠름, Notion AI 미사용, 오프라인 가능)
• 생성/수정 → Notion API MCP (쓰기는 서버 API 필요)

---

지원 플랫폼

OS	Notion DB 경로	상태
macOS	~/Library/Application Support/Notion/notion.db	✅ 검증됨
Windows	%APPDATA%\Notion\notion.db	✅ 지원 (미검증)
Linux	~/.config/Notion/notion.db	⚠️ 비공식

참고: Notion은 공식 Linux 데스크탑 앱을 제공하지 않습니다. Linux에서는 커뮤니티 비공식 빌드(예: notion-app-electron)에서만 동작할 수 있습니다.

---

MCP 도구

notion_local_search

키워드로 페이지 검색

{
  query: string,          // 검색어 (필수)
  type?: "page" | "all",  // 검색 범위 (기본: page)
  limit?: number          // 최대 결과 수 (기본: 20)
}

notion_local_recent

최근 수정된 페이지 목록

{
  limit?: number,   // 최대 결과 수 (기본: 20)
  days?: number     // 며칠 이내 (기본: 30)
}

notion_local_get_page

페이지 전체 내용 조회

{
  pageId: string,   // 페이지 UUID (필수)
  depth?: number    // 중첩 블록 깊이 (기본: 3)
}

notion_local_parent

페이지의 상위 계층 조회

{
  pageId: string    // 페이지 UUID (필수)
}

notion_local_children

페이지의 하위 페이지 목록

{
  pageId: string,   // 페이지 UUID (필수)
  depth?: number    // 탐색 깊이 (기본: 2)
}

---

수동 설정 (고급)

자동 설정이 안 될 경우 수동으로 설정할 수 있습니다.

Claude Desktop Chat

~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "notion-local": {
      "command": "npx",
      "args": ["-y", "@lulee/notion-local-mcp"],
      "env": {
        "NOTION_DB_PATH": "/Users/YOUR_USERNAME/Library/Application Support/Notion/notion.db"
      }
    }
  }
}

Claude Code

~/.claude.json:

{
  "mcpServers": {
    "notion-local": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@lulee/notion-local-mcp"],
      "env": {
        "NOTION_DB_PATH": "/Users/YOUR_USERNAME/Library/Application Support/Notion/notion.db"
      }
    }
  }
}

---

개발

로컬에서 개발하려면:

git clone https://github.com/lulee/notion-local-mcp.git
cd notion-local-mcp
npm install
npm run build
npm run setup  # 로컬 빌드를 Claude에 연결

---

주의사항

• 읽기 전용: 로컬 캐시만 읽으며, Notion 데이터를 수정하지 않습니다.
• Notion 앱 필요: Notion 데스크탑 앱이 설치되어 있어야 캐시가 존재합니다.
• 동기화 지연: 최근 변경사항은 Notion 앱이 동기화될 때까지 반영되지 않을 수 있습니다.

---

라이선스

MIT