Notion Api MCP

🚀 Notion API MCP

A Python server based on the Model Context Protocol (MCP) that provides advanced to - do management and content organization functions through Notion's API. MCP enables AI models to seamlessly integrate with external tools and services, leveraging the powerful capabilities of Notion.

🚀 Quick Start

# Clone the code and set up the environment
git clone https://github.com/yourusername/notion-api-mcp.git
cd notion-api-mcp
uv venv && source .venv/bin/activate  # Windows users can use poetry install or conda create

# Install dependencies
pip install -r requirements.txt

# Run the server
python -m notion_api_mcp

✨ Features

The Python server supports AI models to interact through the Notion API, offering the following features:

• To - do Management: Create, update, and track tasks, supporting rich text formats, deadlines, priorities, and nested subtasks.
• Database Operations: Create and manage Notion databases with custom properties, filters, and views.
• Content Organization: Structure and organize content through Markdown support, hierarchical lists, and block operations.
• Real - time Integration: Interact directly with Notion workspaces, pages, and databases through a clean asynchronous implementation.

Full feature list →

📚 Documentation

• Configuration Details: Detailed configuration options and environment variable descriptions.
• Feature List: Complete list of features and their implementation details.
• Architecture Overview: Tool usage and examples.
• API Reference Documentation: Detailed endpoint information and implementation details.
• Test Coverage Matrix: Test coverage and verification status.
• Dependency Management: Project dependencies and version information.
• Change Log: Development progress and update records.

🔧 Technical Details

Getting Started Guide

Create a Configuration File

Create a config.yaml file in the project root directory with the following content:

database:
  name: "My Notion Database"  # Database name
  id: "YOUR_NOTION_DATABASE_ID"  # Replace with your Notion database ID
  space_id: "YOUR_NOTION_SPACE_ID"  # Replace with the space ID

auth:
  token: "YOUR_NOTION_TOKEN"  # Replace with your Notion API token

Start the Server

# Run the following command in the terminal to start the server
PYTHONPATH=/path/to/project python -m notion_api_mcp

Project Structure

notion_api_mcp/
├── config.py           # Configuration file
├── database.py         # Database operation class
├── models.py           # Pydantic model definitions
├── server.py           # Main service file
└── utils/             # Utility functions

Debugging Tips

• Log Output:
  • Development mode: Console output
  • Production mode: File logging
  • Detailed error information and request - response logs (debug level)
• Set Environment Variables:

export PYTHONPATH=/path/to/project

🚧 Future Development

Planned Improvements

1. Performance Optimization
   • Implement a request caching mechanism.
   • Optimize database query efficiency.
   • Introduce connection pooling technology.
2. Advanced Features
   • Support multi - workspace mode.
   • Provide batch operation functions.
   • Enable real - time update notifications.
   • Enhance advanced search capabilities.
3. Improve Developer Experience
   • Offer interactive API documentation.
   • Add CLI tools.
   • Include more code examples.
   • Introduce performance monitoring.
4. Enhance Testing
   • Conduct performance benchmark testing.
   • Perform load testing.
   • Add new boundary case tests.
   • Expand integration testing.