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 - 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 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" />

2. Give your integration a name (e.g., "AI QA Tracker") and select the appropriate capabilities (read & write)

3. 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:

# 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	Complete setup guide for new users
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:

# 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 for more details.

Claude Desktop Configuration

Edit your Claude Desktop config:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.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

# 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
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
• Model Context Protocol
• Claude Desktop

---

Questions? Check QUICKSTART.md for detailed step-by-step instructions! 🚀