# notion-mcp-fast

[English](#notion-mcp-fast) | [한국어](#한국어)

**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

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

## Setup

### Claude Code

```bash
# 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`:

```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

```json
{
  "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](https://github.com/everything-chalna/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+**

## 설치

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

## 설정

### Claude Code

```bash
# 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` 편집:

```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로 다시 조회