🚀 Notion MCP Server

A powerful Model Context Protocol (MCP) server that connects AI assistants like Claude to your Notion workspace. Seamlessly search, create, and manage your Notion content through natural language conversations!

✨ What This Does

Transform your AI assistant into a Notion powerhouse! With this MCP server, you can:

• 🔍 Search through all your Notion pages and databases

• 📝 Create new pages, databases, and content

• ✏️ Update existing pages and properties

• 📊 Query databases with complex filters

• 🔗 Manage your entire Notion workspace through conversation

🎯 Quick Start

1. Prerequisites

• Python 3.8 or higher

• A Notion workspace

• Nango account (for OAuth authentication)

• Claude Desktop app (for AI integration)

2. Installation

# Clone or download the files
git clone <your-repo-url>
cd notion-mcp-server

# Install dependencies
uv sync

3. Notion Setup

1. Create a Notion Integration:

   • Go to https://www.notion.so/my-integrations

   • Click "New integration"

   • Name it (e.g., "Claude MCP Integration")

   • Select your workspace

   • Set capabilities:

     • ✅ Read content

     • ✅ Insert content

     • ✅ Update content

   • Save and copy your integration token

2. Share Pages with Integration:

   • Open any Notion page you want to access

   • Click "Share" → "Invite"

   • Select your integration

   • Repeat for all pages/databases you want to use

4. Nango Setup (OAuth)

1. Create Nango Account: https://nango.dev

2. Add Notion Integration in your Nango dashboard

3. Configure OAuth with your Notion integration credentials

4. Get your Nango credentials (Base URL, Secret Key, Connection ID)

5. Environment Configuration

Create a .env file with your credentials:

# Nango OAuth Configuration
NANGO_BASE_URL=https://api.nango.dev
NANGO_SECRET_KEY=your_nango_secret_key_here
NANGO_CONNECTION_ID=your_connection_id_here
NANGO_INTEGRATION_ID=notion

# Optional: Direct Notion Token (if not using Nango)
# NOTION_TOKEN=your_direct_notion_token_here

6. Claude Desktop Configuration

Add this to your Claude Desktop configuration file:

On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json On Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "notion": {
      "command": "uvx",
      "args": ["git+https://github.com/Shameerpc5029/notion-mcp.git"],
      "env": {
        "NANGO_BASE_URL": "https://api.nango.dev",
        "NANGO_SECRET_KEY": "your_nango_secret_key",
        "NANGO_CONNECTION_ID": "your_connection_id", 
        "NANGO_INTEGRATION_ID": "notion"
      }
    }
  }
}

7. Test the Connection

# Test the server directly
python notion-mcp-server.py

# Or restart Claude Desktop and try asking:
# "Search my Notion for meeting notes"
# "Create a new task in my project database"

🛠️ Available Tools

💬 Example Conversations with Claude

Once configured, you can have natural conversations like:

Task Management

You: "Show me all my incomplete tasks"
Claude: [Queries your tasks database and shows open items]

You: "Create a new task called 'Review MCP integration' due next Friday"
Claude: [Creates the task with proper due date]

You: "Mark the first task as completed"
Claude: [Updates the task status to Done]

Content Creation

You: "Create a meeting notes page for today's standup"
Claude: [Creates a new page with meeting template]

You: "Add action items from our discussion to that page"
Claude: [Appends bullet points with the action items]

Research & Organization

You: "Search for all pages mentioning 'API documentation'"
Claude: [Finds and lists relevant pages]

You: "Create a new database to track our API endpoints"
Claude: [Creates a structured database with relevant properties]

🔧 Troubleshooting

Common Issues

"Authentication Error"

• Check your .env file has correct Nango credentials

• Verify your Nango integration is active

• Ensure your Notion integration has proper capabilities

"Page not found" errors

• Make sure you've shared the page/database with your integration

• Check the page/database ID is correct

• Verify the integration has read access

Claude can't find the server

• Check the absolute path in claude_desktop_config.json is correct

• Ensure Python is in your system PATH

• Try running the server manually first to test

"No access token found"

• Verify Nango connection is working

• Check your NANGO_CONNECTION_ID matches your actual connection

• Try refreshing your Nango integration

Debug Mode

Run with verbose logging:

python notion-mcp-server.py --debug

Manual Testing

Test individual functions:

from notion_mcp_server import NotionClient

client = NotionClient()
user = client.get_current_user()
print(f"Connected as: {user.get('name')}")

🔒 Security Notes

• Never commit your to version control

• Keep your Nango secret key secure

• Only share Notion pages that the integration needs access to

• Regularly review your integration's access in Notion settings

📁 File Structure

notion-mcp/
├── main.py    # Main MCP server
├── pyproject.toml        # Python dependencies  
├── .env.example
├── .env                   # Your credentials (don't commit!)
├── README.md              # This file

🆘 Getting Help

1. Check the logs - Look for error messages in Claude Desktop or terminal

2. Verify permissions - Ensure your integration can access the pages

3. Test manually - Run the server directly to isolate issues

4. Check Notion status - Sometimes Notion API has outages

🎉 What's Next?

Once you're up and running:

• Try creating complex database queries

• Set up automated content creation workflows

• Use Claude to help organize and restructure your Notion workspace

• Explore advanced filtering and sorting options

📄 License

This project is open source. Feel free to modify and adapt for your needs!

Happy Notion-ing with Claude! 🎊

Made with ❤️ for the AI-powered productivity enthusiasts