Notion MCP Server

🚀 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