notion-mcp-fast

English | 한국어

Fast, read-only MCP server for Notion - reads directly from local SQLite cache, no API calls needed.

Why?

The official Notion MCP makes API calls for every read operation:

• Slow: Network latency on every request
• Rate limited: API quotas apply
• Context heavy: Verbose responses consume AI context window

notion-mcp-fast reads directly from Notion's local SQLite cache:

• Instant: No network calls, <10ms response times
• Unlimited: No API rate limits
• Minimal: Clean, concise responses

Requirements

• macOS only (Notion stores SQLite cache at a macOS-specific path)
• Notion desktop app installed and logged in
• Python 3.10+

Installation

git clone https://github.com/lucid-jin/notion-mcp-fast.git
cd notion-mcp-fast

Setup

Claude Code

# Add MCP server (use absolute path)
claude mcp add notion-fast -- uvx --from /path/to/notion-mcp-fast notion-mcp-fast

# Example with home directory
claude mcp add notion-fast -- uvx --from ~/notion-mcp-fast notion-mcp-fast

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "notion-fast": {
      "command": "uvx",
      "args": ["--from", "/path/to/notion-mcp-fast", "notion-mcp-fast"]
    }
  }
}

Recommended: Use with Official Notion MCP

For a complete setup, use both:

• notion-fast: Fast reads from local cache
• Official Notion MCP: Writes and real-time data

{
  "mcpServers": {
    "notion-fast": {
      "command": "uvx",
      "args": ["notion-mcp-fast"]
    },
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_API_KEY": "your-api-key"
      }
    }
  }
}

Available Tools

Tool	Description
list_pages	List pages with optional search and filtering
get_page	Get a page with its child blocks
list_databases	List all databases (collections)
get_database	Get database schema and details
query_database	Query rows from a database
list_users	List all users
get_user	Get user details
list_spaces	List all workspaces
search	Search across all pages by title
get_summary	Get counts of all cached entities

How It Works

┌─────────────────────────────────────┐
│         Notion Desktop App          │
│                                     │
│   Syncs data → SQLite database      │
└─────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────┐
│  ~/Library/Application Support/     │
│  Notion/notion.db                   │
│                                     │
│  SQLite with 162K+ blocks           │
└─────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────┐
│        notion-mcp-fast              │
│                                     │
│  • Reads SQLite directly            │
│  • 5-minute TTL cache               │
│  • MCP protocol interface           │
└─────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────┐
│     Claude / AI Assistant           │
│                                     │
│  Instant access to Notion data!     │
└─────────────────────────────────────┘

Limitations

• Read-only: Cannot create or modify Notion content
• macOS only: SQLite path is macOS-specific
• Cache lag: Data reflects last Notion app sync (usually <1 min)
• Requires Notion app: Desktop app must be installed and logged in

Troubleshooting

"Notion database not found"

1. Ensure Notion desktop app is installed
2. Open Notion app and let it sync
3. Check if file exists: ls ~/Library/Application\ Support/Notion/notion.db

Stale data

Notion caches data locally with frequent syncs. If data seems stale:

1. Open Notion app
2. Navigate to the page/database
3. Wait a few seconds for sync
4. Re-query via MCP

License

MIT

Inspired By

• linear-mcp-fast - Same concept for Linear

---

한국어

Notion용 초고속 읽기 전용 MCP 서버 - API 호출 없이 로컬 SQLite 캐시에서 직접 읽습니다.

왜 만들었나요?

공식 Notion MCP는 매번 API를 호출합니다:

• 느림: 매 요청마다 네트워크 지연
• 제한: API 호출 제한 적용
• 무거움: 응답이 커서 AI 컨텍스트 윈도우 소모

notion-mcp-fast는 로컬 SQLite 캐시에서 직접 읽습니다:

• 즉시 응답: 네트워크 호출 없음, <10ms 응답
• 무제한: API 제한 없음
• 가벼움: 깔끔하고 간결한 응답

요구사항

• macOS 전용 (Notion이 macOS 특정 경로에 SQLite 캐시 저장)
• Notion 데스크톱 앱 설치 및 로그인 필요
• Python 3.10+

설치

git clone https://github.com/lucid-jin/notion-mcp-fast.git
cd notion-mcp-fast

설정

Claude Code

# MCP 서버 추가 (절대 경로 사용)
claude mcp add notion-fast -- uvx --from /path/to/notion-mcp-fast notion-mcp-fast

# 홈 디렉토리 예시
claude mcp add notion-fast -- uvx --from ~/notion-mcp-fast notion-mcp-fast

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json 편집:

{
  "mcpServers": {
    "notion-fast": {
      "command": "uvx",
      "args": ["--from", "/path/to/notion-mcp-fast", "notion-mcp-fast"]
    }
  }
}

제공 도구

도구	설명
list_pages	페이지 목록 (검색/필터 지원)
get_page	페이지 상세 + 하위 블록
list_databases	데이터베이스 목록
get_database	데이터베이스 스키마 조회
query_database	데이터베이스 행 조회
list_users	사용자 목록
get_user	사용자 상세
list_spaces	워크스페이스 목록
search	제목으로 전체 검색
get_summary	캐시 통계

작동 원리

Notion 데스크톱 앱
    ↓ (로컬 동기화)
~/Library/Application Support/Notion/notion.db (SQLite)
    ↓ (직접 읽기)
notion-mcp-fast (5분 TTL 캐시)
    ↓ (MCP 프로토콜)
Claude / AI 어시스턴트 → 즉시 응답!

성능

상황	응답 시간
Cold cache (첫 요청)	~5초
Warm cache (이후 요청)	<1ms

제한사항

• 읽기 전용: Notion 콘텐츠 생성/수정 불가
• macOS 전용: SQLite 경로가 macOS 고정
• 캐시 지연: Notion 앱 동기화 후 반영 (보통 <1분)
• 앱 필요: Notion 데스크톱 앱 설치 필수

문제 해결

"Notion database not found" 오류

1. Notion 데스크톱 앱 설치 확인
2. Notion 앱 열고 동기화 대기
3. 파일 존재 확인: ls ~/Library/Application\ Support/Notion/notion.db

데이터가 오래됨

1. Notion 앱 열기
2. 해당 페이지/데이터베이스로 이동
3. 몇 초 대기 (동기화)
4. MCP로 다시 조회