# Notion MCP Server

[![npm version](https://badge.fury.io/js/@itsyuimorii%2Fnotion-mcp-server.svg)](https://www.npmjs.com/package/@itsyuimorii/notion-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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

![Notion Integration Setup](docs/images/notion-integration-create.png)

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

![Notion Integration Token](docs/images/notion-integration-token.png)

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) 🚀