# Notion MCP Server - AI-Notion Integration
A Model Context Protocol (MCP) server that seamlessly integrates Claude AI with Notion databases. Save your conversations, Q&A pairs, and learning progress directly to Notion from Claude Desktop.
## 🎯 What is This?
This project allows Claude (via Claude Desktop) to:
- ✅ Save conversations and Q&A pairs to Notion automatically
- ✅ Query your Notion database from Claude
- ✅ Track learning progress with mastery levels
- ✅ Organize information in a structured database
## 📋 Quick Start
**New to this project?** Start here: **[QUICKSTART.md](./QUICKSTART.md)** - A complete step-by-step guide for first-time users!
## Setup
1. Clone the repository
2. Install dependencies:
```
npm install
```
3. Create a `.env` file with the following variables:
```
NOTION_API_TOKEN=your_notion_integration_token
NOTION_DATABASE_ID=your_notion_database_id
NOTION_PARENT_PAGE_ID=your_notion_page_id (only needed for database setup)
```
## Notion Integration Setup
1. Go to [Notion Integrations](https://www.notion.so/my-integrations) and create a new integration
<img width="600" alt="Screenshot 2026-01-31 at 7 50 23 PM" src="https://github.com/user-attachments/assets/d1373f24-663f-4c87-8e54-582707f411e6" />
3. Give your integration a name (e.g., "AI QA Tracker") and select the appropriate capabilities (read & write)
4. Copy the "Internal Integration Token" and paste it into your `.env` file
<img width="600" alt="Screenshot 2026-01-31 at 7 50 11 PM" src="https://github.com/user-attachments/assets/2e6c446f-cd99-4c30-94bf-f5933bee35ca" />
5. Share your Notion database with your integration
## Database Setup
To create a new database structure for tracking AI questions/answers:
```bash
# 1. Install dependencies
npm install
# 2. Configure .env (copy from .env.example)
cp .env.example .env
# Edit .env with your Notion credentials
# 3. Build the project
npm run build
# 4. Configure Claude Desktop
# Edit ~/Library/Application\ Support/Claude/claude_desktop_config.json
# See QUICKSTART.md Step 3 for details
# 5. Restart Claude Desktop
# You're ready to use it!
```
## 📚 Documentation
| Document | Purpose |
|----------|---------|
| [**QUICKSTART.md**](./QUICKSTART.md) | Complete setup guide for new users |
| [**README.md**](./README.md) | This file - project overview |
| `.env.example` | Configuration template |
## 🔧 System Requirements
- **Node.js**: 18 or higher
- **npm**: 9 or higher
- **Operating System**: macOS, Windows, or Linux
- **Notion Account**: With an active workspace
- **Claude Desktop**: Latest version
## 🚀 Core Features
### 1. **Notion Integration**
- Create and manage Notion databases from your code
- Automatic database setup with proper structure
- Full read/write access through Notion API
### 2. **MCP Server**
- Exposes tools to Claude Desktop via MCP protocol
- Built-in support for ES Modules (ESM)
- Type-safe with TypeScript
### 3. **AI-Ready Tools**
The server provides these tools for Claude to use:
- `notion_ai_save_entry` - Save Q&A to Notion
- `notion_query_database` - Search your Notion database
- `notion_update_mastery` - Track learning progress
## 📁 Project Structure
```
notion-mcp-server/
├── src/
│ ├── index.ts # Main MCP server entry point
│ ├── config.ts # Environment & config validation
│ ├── types.ts # TypeScript type definitions
│ ├── setup-database.ts # Database initialization script
│ ├── test-notion.ts # Notion API connection tests
│ ├── mock-test.ts # Tests without real Notion
│ └── test.ts # MCP server tests
├── dist/ # Compiled JavaScript (auto-generated)
├── .env # Your configuration (don't commit!)
├── .env.example # Configuration template
├── tsconfig.json # TypeScript settings
├── package.json # Dependencies & scripts
├── QUICKSTART.md # First-time user guide
└── README.md # This file
```
## 🔑 Configuration
### Environment Variables
Create a `.env` file in the project root with:
```env
# Required: Notion API Integration Token
NOTION_API_TOKEN=ntn_your_token_here
# Required: Notion page ID where database will be created
NOTION_PARENT_PAGE_ID=your_page_id_here
# Optional: Existing database ID (auto-created on first run)
NOTION_DATABASE_ID=your_database_id_here
```
See **[.env.example](./.env.example)** for more details.
### Claude Desktop Configuration
Edit your Claude Desktop config:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"notion-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"
}
}
}
}
```
## 🛠️ Available Commands
```bash
# Install dependencies
npm install
# Build the project (TypeScript → JavaScript)
npm run build
# Run tests
npm run test
# Test Notion connection specifically
npm run test-notion
# Start in development mode with auto-reload
npm run dev
# Start the server (production)
npm start
```
## 📖 How It Works
```
1. You write in Claude Desktop
2. Claude uses the Notion tools
3. MCP Server (dist/index.js) handles the request
4. Notion API saves your data
5. Your Notion database is updated
```
## ❓ Why TypeScript → JavaScript?
**Key Question**: Why do we need to build?
- **Source**: `src/index.ts` (TypeScript with type checking)
- **Build**: `npm run build` (compilation step)
- **Runtime**: `dist/index.js` (plain JavaScript)
- **Why**: Claude Desktop runs Node.js, which needs `.js` files, not `.ts`
```
Development: src/index.ts
↓ npm run build
Production: dist/index.js ← Claude Desktop executes this
```
## 🔐 Security Notes
- ⚠️ **Never commit `.env` file** - It contains your API token
- ✅ `.env` is already in `.gitignore`
- ✅ Safe to share: `src/`, `package.json`, `tsconfig.json`, `.env.example`
- ❌ Never share: `.env`, `dist/`, `node_modules/`
## 🐛 Troubleshooting
### Claude Desktop shows "Failed to connect"
1. Check `.env` file has correct values
2. Run `npm run build` to generate `dist/index.js`
3. Verify path in Claude Desktop config is correct
4. Restart Claude Desktop
### "NOTION_API_TOKEN is not set"
1. Create `.env` file (copy from `.env.example`)
2. Add your actual Notion token
3. Restart Claude Desktop
### "Database permission denied"
1. Go to https://www.notion.so/my-integrations
2. Find your integration
3. Share your Notion page with the integration
4. Restart Claude Desktop
### "Cannot find module dist/index.js"
1. Run `npm install` first
2. Run `npm run build`
3. Check `dist/` folder exists and contains `index.js`
## 📚 Next Steps
1. **First time?** Read [QUICKSTART.md](./QUICKSTART.md)
2. **Want to customize?** Modify `src/index.ts` to add new tools
3. **Need help?** Check QUICKSTART.md's FAQ section
## 📝 Git Best Practices
### What to commit:
- `src/` - Your source code
- `package.json` - Dependencies list
- `tsconfig.json` - Build configuration
- `.env.example` - Configuration template
- `QUICKSTART.md` - Documentation
- `.gitignore` - Git settings
### What NOT to commit:
- `dist/` - Regenerate with `npm run build`
- `node_modules/` - Regenerate with `npm install`
- `.env` - Contains secrets, already ignored
- `*.log` - Log files
- `.DS_Store` - macOS system files
## 🤝 Contributing
To modify or extend this project:
1. Edit files in `src/`
2. Run `npm run build` to recompile
3. Test locally: `npm run test`
4. Restart Claude Desktop to see changes
## 📄 License
ISC
## 🙏 Acknowledgments
- [Notion API Documentation](https://developers.notion.com/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Claude Desktop](https://claude.ai/download)
---
**Questions?** Check [QUICKSTART.md](./QUICKSTART.md) for detailed step-by-step instructions! 🚀
