Notion API MCP

A Model Context Protocol (MCP) server that provides advanced todo list management and content organization capabilities through Notion's API. MCP enables AI models to interact with external tools and services, allowing seamless integration with Notion's powerful features.

MCP Overview

Python-based MCP server that enables AI models to interact with Notion's API, providing:

Todo Management: Create, update, and track tasks with rich text, due dates, priorities, and nested subtasks
Database Operations: Create and manage Notion databases with custom properties, filters, and views
Content Organization: Structure and format content with Markdown support, hierarchical lists, and block operations
Real-time Integration: Direct interaction with Notion's workspace, pages, and databases through clean async implementation

Full feature list →

Quick Start

# Clone and setup
git clone https://github.com/yourusername/notion-api-mcp.git
cd notion-api-mcp
uv venv && source .venv/bin/activate

# Install and configure
uv pip install -e .
cp .env.integration.template .env

# Add your Notion credentials to .env:
# NOTION_API_KEY=ntn_your_integration_token_here
# NOTION_PARENT_PAGE_ID=your_page_id_here  # For new databases
# NOTION_DATABASE_ID=your_database_id_here  # For existing databases

# Run the server
python -m notion_api_mcp

Getting Started

1. Create a Notion Integration

Go to https://www.notion.so/my-integrations
Click "New integration"
Name your integration (e.g., "My MCP Integration")
Select the workspace where you'll use the integration
Copy the "Internal Integration Token" - this will be your NOTION_API_KEY
- Should start with "ntn_"

2. Set Up Notion Access

You'll need either a parent page (for creating new databases) or an existing database ID:

Option A: Parent Page for New Databases

Open Notion in your browser
Create a new page or open an existing one where you want to create databases
Click the ••• menu in the top right
Select "Add connections" and choose your integration
Copy the page ID from the URL - it's the string after the last slash and before the question mark
- Example: In https://notion.so/myworkspace/123456abcdef..., the ID is 123456abcdef...
- This will be your NOTION_PARENT_PAGE_ID

Option B: Existing Database

Open your existing Notion database
Make sure it's connected to your integration (••• menu > Add connections)
Copy the database ID from the URL
- Example: In https://notion.so/myworkspace/123456abcdef...?v=..., the ID is 123456abcdef...
- This will be your NOTION_DATABASE_ID

3. Install the MCP Server

Create virtual environment:

cd notion-api-mcp
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Install dependencies:

uv pip install -e .

Configure environment:

cp .env.integration.template .env

Edit .env with your Notion credentials:

NOTION_API_KEY=ntn_your_integration_token_here

# Choose one or both of these depending on your needs:
NOTION_PARENT_PAGE_ID=your_page_id_here  # For creating new databases
NOTION_DATABASE_ID=your_database_id_here  # For working with existing databases

4. Configure Claude Desktop

IMPORTANT: While the server supports both .env files and environment variables, Claude Desktop specifically requires configuration in its config file to use the MCP.

Add to Claude Desktop's config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "notion-api": {
      "command": "/path/to/your/.venv/bin/python",
      "args": ["-m", "notion_api_mcp"],
      "env": {
        "NOTION_API_KEY": "ntn_your_integration_token_here",
        
        // Choose one or both:
        "NOTION_PARENT_PAGE_ID": "your_page_id_here",
        "NOTION_DATABASE_ID": "your_database_id_here"
      }
    }
  }
}

Note: Even if you have a .env file configured, you must add these environment variables to the Claude Desktop config for Claude to use the MCP. The .env file is primarily for local development and testing.

Documentation

Configuration Details - Detailed configuration options and environment variables
Features - Complete feature list and capabilities
Architecture - Overview of available tools and usage examples
API Reference - Detailed API endpoints and implementation details
Test Coverage Matrix - Test coverage and validation status
Dependencies - Project dependencies and version information
Changelog - Development progress and updates

Development

The server uses modern Python async features throughout:

Type-safe configuration using Pydantic models
Async HTTP using httpx for better performance
Clean MCP integration for exposing Notion capabilities
Proper resource cleanup and error handling

Debugging

The server includes comprehensive logging:

Console output for development
File logging when running as a service
Detailed error messages
Request/response logging at debug level

Set PYTHONPATH to include the project root when running directly:

PYTHONPATH=/path/to/project python -m notion_api_mcp

Future Development

Planned enhancements:

Performance Optimization
- Add request caching
- Optimize database queries
- Implement connection pooling
Advanced Features
- Multi-workspace support
- Batch operations
- Real-time updates
- Advanced search capabilities
Developer Experience
- Interactive API documentation
- CLI tools for common operations
- Additional code examples
- Performance monitoring
Testing Enhancements
- Performance benchmarks
- Load testing
- Additional edge cases
- Extended integration tests