README.md
Notion MCP Server
AI-powered knowledge management with Notion integration and spaced repetition learning system.
āØ Features
- š Auto-save conversations - Save AI Q&A to Notion with intelligent categorization
- š Advanced search - Query by date, category, tags, and full-text search
- š§ Spaced repetition - Science-based review scheduling (1/2/4/7/15 days)
- š Progress tracking - Track mastery levels (ā-āāāāā) and review counts
š¦ Installation
Option 1: NPM (Recommended)
npm install -g @itsyuimorii/notion-mcp-server
Option 2: From Source
git clone https://github.com/itsyuimorii/notion-mcp-server.git
cd notion-mcp-server
npm install
npm run build
š Quick Start
1. Create Notion Integration
- Go to Notion Integrations and create a new integration
- Give your integration a name (e.g., "AI Learning Tracker") and select the appropriate capabilities (read & write)
- Copy the "Internal Integration Token" and paste it into your
.envfile
- Share your Notion page with the integration
2. Configure Environment
Create a .env file:
NOTION_API_TOKEN=ntn_your_token_here
NOTION_PARENT_PAGE_ID=your_page_id_here
NOTION_DATABASE_ID=your_database_id_here # Optional
3. Configure Claude Desktop
Edit ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"notion-mcp-server": {
"command": "node",
"args": ["/path/to/notion-mcp-server/dist/index.js"],
"env": {
"NOTION_API_TOKEN": "ntn_your_token",
"NOTION_PARENT_PAGE_ID": "your_page_id",
"NOTION_DATABASE_ID": "your_database_id"
}
}
}
}
4. Restart Claude Desktop
You're ready to use it!
š ļø Available Tools
| Tool | Description |
|---|---|
notion_setup_database |
Create pre-configured database with spaced repetition fields |
notion_ai_save_entry |
Save Q&A with auto-categorization and tags |
notion_query_database |
Search with filters (date/category/tags) |
notion_check_reviews |
Check overdue and upcoming reviews |
notion_update_mastery |
Update mastery level and schedule next review |
š Project Structure
notion-mcp-server/
āāā src/
ā āāā index.ts # Main MCP server
ā āāā config.ts # Configuration
ā āāā types.ts # TypeScript types
āāā docs/
ā āāā images/ # Documentation images
āāā QUICKSTART.md # Detailed setup guide
āāā DEMO_SCENARIOS.md # Usage examples
āāā LICENSE # MIT License
āāā package.json # Dependencies
š Documentation
- QUICKSTART.md - Complete setup guide
- DEMO_SCENARIOS.md - Real-world usage examples
š§ Requirements
- Node.js 18+
- npm 9+
- Notion account with workspace
- Claude Desktop (latest version)
š Troubleshooting
Connection failed?
- Check
.envfile has correct token - Run
npm run buildto generatedist/index.js - Verify path in Claude config
- Restart Claude Desktop
Database permission denied?
- Go to your Notion page
- Click "..." ā "Add connections"
- Select your integration
- Restart Claude Desktop
š License
MIT - see LICENSE
š Links
New to this project? Start with QUICKSTART.md š
Tools 5
notion_setup_databaseCreate pre-configured database with spaced repetition fieldsnotion_ai_save_entrySave Q&A with auto-categorization and tagsnotion_query_databaseSearch with filters (date/category/tags)notion_check_reviewsCheck overdue and upcoming reviewsnotion_update_masteryUpdate mastery level and schedule next reviewEnvironment Variables
NOTION_API_TOKENrequiredInternal Integration Token from NotionNOTION_PARENT_PAGE_IDrequiredThe ID of the Notion page to host the databaseNOTION_DATABASE_IDOptional ID of an existing Notion databaseTry it
āSave this Q&A pair to my Notion database with the tag 'coding'.
āWhat are my overdue reviews for today?
āSearch my Notion database for entries related to 'JavaScript' from the last week.
āUpdate the mastery level for the entry about 'MCP architecture' to 5 stars.
āSet up a new spaced repetition database in my Notion workspace.