Content
# Tool List
[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
