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
Getting Started
1. Create a Notion Integration
- 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
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
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
3. Install the MCP Server
- Create virtual environment:
- Install dependencies:
- Configure environment:
- Edit .env with your Notion credentials:
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):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:Future Development
Planned enhancements:
- Performance Optimization
- Advanced Features
- Developer Experience
- Testing Enhancements
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
Getting Started
1. Create a Notion Integration
- 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
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
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
3. Install the MCP Server
- Create virtual environment:
- Install dependencies:
- Configure environment:
- Edit .env with your Notion credentials:
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):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:Future Development
Planned enhancements:
- Performance Optimization
- Advanced Features
- Developer Experience
- Testing Enhancements