pbohannon/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
bash
# 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
1. Go to https://www.notion.so/my-integrations
2. Click "New integration"
3. Name your integration (e.g., "My MCP Integration")
4. Select the workspace where you'll use the integration
5. 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
1. Open Notion in your browser
2. Create a new page or open an existing one where you want to create databases
3. Click the ••• menu in the top right
4. Select "Add connections" and choose your integration
5. 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
1. Open your existing Notion database
2. Make sure it's connected to your integration (••• menu > Add connections)
3. 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
1. Create virtual environment:
bash
cd notion-api-mcp
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
2. Install dependencies:
bash
uv pip install -e .
3. Configure environment:
bash
cp .env.integration.template .env
4. Edit .env with your Notion credentials:
env
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