# Notion MCP Server
[](https://www.npmjs.com/package/@itsyuimorii/notion-mcp-server)
[](https://opensource.org/licenses/MIT)
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)
```bash
npm install -g @itsyuimorii/notion-mcp-server
```
### Option 2: From Source
```bash
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
1. Go to [Notion Integrations](https://www.notion.so/my-integrations) and create a new integration
2. Give your integration a name (e.g., "AI Learning Tracker") and select the appropriate capabilities (read & write)
3. Copy the "Internal Integration Token" and paste it into your `.env` file
4. Share your Notion page with the integration
### 2. Configure Environment
Create a `.env` file:
```env
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`:
```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](./QUICKSTART.md)** - Complete setup guide
- **[DEMO_SCENARIOS.md](./DEMO_SCENARIOS.md)** - Real-world usage examples
## 🔧 Requirements
- Node.js 18+
- npm 9+
- Notion account with workspace
- Claude Desktop (latest version)
## 🐛 Troubleshooting
**Connection failed?**
1. Check `.env` file has correct token
2. Run `npm run build` to generate `dist/index.js`
3. Verify path in Claude config
4. Restart Claude Desktop
**Database permission denied?**
1. Go to your Notion page
2. Click "..." → "Add connections"
3. Select your integration
4. Restart Claude Desktop
## 📄 License
MIT - see [LICENSE](./LICENSE)
## 🔗 Links
- [NPM Package](https://www.npmjs.com/package/@itsyuimorii/notion-mcp-server)
- [GitHub Repository](https://github.com/itsyuimorii/notion-mcp-server)
- [Issues](https://github.com/itsyuimorii/notion-mcp-server/issues)
---
**New to this project?** Start with [QUICKSTART.md](./QUICKSTART.md) 🚀
