Notion MCP Server V2 🚀

A comprehensive Model Context Protocol (MCP) server for Notion integration with enhanced functionality, robust error handling, production-ready features, and bulletproof validation.

✨ Features

🔧 Core Operations

• ✅ Search: Find pages and databases with advanced filtering

• ✅ Page Operations: Create, read, update pages with full content support

• ✅ Content Management: Add paragraphs, headings, bullet points, todos, links, and bookmarks

• ✅ Database Operations: List and query databases

🔗 Advanced Content Types (NEW)

• ✅ Bookmarks: Add external website links with URL validation

• ✅ Link to Page: Create internal links between Notion pages

• ✅ Rich Content: Support for all major Notion block types

• ✅ Content Splitting: Automatic handling of long content (2000+ chars)

📊 Analytics & Insights

• ✅ Workspace Analytics: Total pages, databases, recent activity

• ✅ Content Analytics: Structure analysis and metrics

• ✅ Activity Tracking: Recent edits and usage patterns

• ✅ Performance Metrics: Optimized with configurable timeouts

🔄 Bulk Operations (OPTIMIZED)

• ✅ Smart Pagination: Prevents timeouts with configurable limits

• ✅ Bulk Content Addition: Add multiple content blocks at once

• ✅ Bulk Page Operations: Create and manage multiple pages

• ✅ Performance Controls: Optional block counts for faster responses

🌐 API Interfaces

• ✅ FastAPI REST API: Production-ready HTTP endpoints

• ✅ Interactive CLI: Command-line interface for direct usage

• ✅ MCP Compatible: Full Model Context Protocol support

• ✅ Agent Integration: Unified endpoint for AI agents

🛡️ Production Features (ENHANCED)

• ✅ Bulletproof Validation: Comprehensive input validation and error handling

• ✅ Configuration Management: Environment-based settings

• ✅ Smart Error Recovery: Detailed error messages and recovery guidance

• ✅ Health Checks: Monitoring and status endpoints with feature detection

• ✅ Structured Logging: Configurable logging with performance insights

• ✅ CORS Support: Cross-origin resource sharing

• ✅ Timeout Optimization: Dynamic timeouts based on operation complexity

🧪 Testing & Quality (COMPREHENSIVE)

• ✅ 46KB Test Suite: 1,158 lines of comprehensive tests

• ✅ 13+ Test Categories: Core, content, bulk, links, analytics, edge cases

• ✅ Validation Testing: Tests for all error scenarios and edge cases

• ✅ Performance Testing: Timeout and optimization validation

• ✅ Detailed Reporting: JSON reports with timing and categorization

🏗️ Architecture

📦 Installation

Prerequisites

• Python 3.8+

• Notion account with integration token

• pip or conda package manager

Setup

1. Install Dependencies

2. Environment Configuration Create a .env file in your project root:

3. Get Your Notion Token

• Go to Notion Integrations

• Create a new integration

• Copy the token (starts with ntn_)

• Share your pages/databases with the integration

🚀 Usage

1. FastAPI Server (Production)

Start the server:

Server will be available at:

• API: http://localhost:8081

• Documentation: http://localhost:8081/docs

• Health Check: http://localhost:8081/health

2. Interactive CLI

3. Python Integration

📚 API Documentation

🔍 Search Endpoint

📄 Create Page

📖 Read Page

✏️ Add Content (ENHANCED)

Supported content types:

• paragraph - Regular text

• heading_1 - Large heading

• heading_2 - Medium heading

• heading_3 - Small heading

• bulleted_list_item - Bullet point

• to_do - Checkbox item

• bookmark - External website link (NEW)

• link_to_page - Internal page link (NEW)

🔗 Link Content Types (NEW)

Add Bookmark (External Link):

Add Link to Page (Internal Link):

🔄 Bulk Content Addition (ENHANCED)

📊 Analytics

Analytics types: workspace, content, activity, database

🔄 Bulk Operations (OPTIMIZED)

Optimization options:

• limit: Number of pages to process (1-50)

• include_block_counts: Whether to calculate block counts (slower)

Operations: list, analyze, create

🤖 Agent Integration

Available actions: search, read_page, create_page, add_content, bulk_add_content, analytics, bulk_operations

🧪 Testing (COMPREHENSIVE)

Run the comprehensive test suite:

Test Coverage (1,158 lines, 13+ categories):

• ✅ Core Operations: Health checks, search, page creation/reading

• ✅ Content Addition: All content types including links and bookmarks

• ✅ Bulk Content: Multiple content blocks and optimization

• ✅ Link Functionality: Bookmark and link_to_page validation

• ✅ Analytics: All analytics types and performance

• ✅ Bulk Operations: Optimized pagination and limits

• ✅ Agent Integration: All agent query actions

• ✅ Edge Cases: Error handling, validation, timeouts

• ✅ Exception Handling: Network issues, invalid inputs

Test Features:

• 🎯 Detailed Reporting: Success rates, timing, categorization

• 📊 Performance Insights: Response times and bottlenecks

• 📄 JSON Reports: Exportable test results with timestamps

• 🧹 Cleanup Scripts: Automatic test data management

⚙️ Configuration

Environment Variables

Configuration Validation

The server automatically validates all configuration on startup and provides clear error messages for invalid settings.

🔧 Integration Examples

With AI Agents

With Your Chatbot

📈 Performance Features (ENHANCED)

• Async Operations: Non-blocking I/O for better performance

• Smart Timeouts: Dynamic timeouts (30s standard, 60s bulk, 45s analytics)

• Pagination Controls: Configurable limits to prevent timeouts

• Connection Pooling: Efficient Notion API connections

• Request Validation: Fast input validation and sanitization

• Error Recovery: Graceful handling of API failures

• Memory Efficient: Optimized for low memory usage

• Progress Yielding: Prevents blocking during bulk operations

🛡️ Security & Validation Features (BULLETPROOF)

• Token Validation: Automatic Notion token validation

• Input Sanitization: Protection against malicious input

• Comprehensive Validation: All content types validated

  • Bookmark URLs must be valid HTTP/HTTPS

  • Page references must exist

  • Content length limits enforced

  • Required fields validation

• Rate Limiting Ready: Framework for rate limiting (configurable)

• CORS Support: Secure cross-origin requests

• Environment Isolation: Secure environment variable handling

• HTTP Status Handling: Proper error code processing

📋 Error Handling (ENHANCED)

The server provides detailed error messages for all scenarios:

Validation Errors

• Missing URLs: "URL is required for bookmark content type"

• Invalid Page References: "Target page not found: page-name"

• Empty Content: "Content cannot be empty"

• Invalid Content Types: Clear list of supported types

API Errors

• Invalid Tokens: Clear guidance for token setup

• Missing Pages: Helpful suggestions for page access

• API Limits: Graceful handling of Notion API limits

• Network Issues: Automatic retry mechanisms

• Timeout Prevention: Smart limits and pagination

HTTP Status Codes

• 200: Successful operations

• 400: Validation errors (missing fields, invalid formats)

• 404: Resource not found (pages, invalid references)

• 500: Server errors (with detailed diagnostics)

• 503: Server not initialized

🆔 Version History

V2.1.0 (Current) (MAJOR UPDATE)

• 🔗 Link Functionality: Bookmarks and link_to_page support

• 🛡️ Bulletproof Validation: Comprehensive input validation

• ⚡ Timeout Optimization: Fixed bulk operations with smart pagination

• 🧪 Enhanced Test Suite: 48KB comprehensive testing (1,158 lines)

• 📊 HTTP Status Handling: Proper error code processing in tests

• 🎯 Performance Controls: Configurable timeouts and limits

• 📈 Smart Content: AI-friendly content parsing helpers

V2.0.0 (Previous)

• ✅ Complete rewrite with enhanced features

• ✅ Configuration management system

• ✅ Basic test suite

• ✅ Production-ready error handling

• ✅ Bulk operations support

• ✅ Enhanced content management

• ✅ Agent integration endpoints

V1.0.0 (Legacy)

• ✅ Basic MCP server functionality

• ✅ Core operations (search, read, create)

• ✅ Simple CLI interface

🤝 Contributing

1. Fork the repository

2. Create a feature branch: git checkout -b feature-name

3. Make your changes with tests

4. Run the comprehensive test suite: python test_server.py

5. Ensure all tests pass (aim for 90%+ success rate)

6. Submit a pull request

Testing Requirements:

• All new features must include tests

• Validation scenarios must be covered

• Performance implications should be documented

• Error handling paths must be tested

📞 Support

If you encounter issues:

1. Check Configuration: Ensure all environment variables are set correctly

2. Verify Token: Make sure your Notion token is valid and has proper permissions

3. Run Health Check: Visit /health endpoint to verify server status

4. Run Test Suite: Use python test_server.py to identify specific issues

5. Check Logs: Review server logs for detailed error messages

6. Test Validation: Ensure your content meets validation requirements

Common Issues:

• Link validation errors: Ensure URLs start with http/https

• Timeout issues: Use pagination controls for large operations

• Page not found: Verify page sharing with integration

• Content too long: Content blocks limited to 2000 characters

📧 Contact Information

For direct support or questions:

• 📱 Phone: +918449035579

• 📧 Email: ankitmalik844903@gmail.com

• 👨‍💻 Developer: Ankit Malik

Feel free to reach out for:

• ✅ Technical support and troubleshooting

• ✅ Feature requests and suggestions

• ✅ Integration assistance

• ✅ Bug reports and issues

• ✅ Custom development needs

📄 License

This project is part of the Agentic Long-Term Memory system.

🎉 Your Notion MCP Server V2.1 is bulletproof and production-ready!

⚡ New in V2.1:

• 🔗 Link Support - Bookmarks and internal page links

• 🛡️ Bulletproof Validation - Comprehensive error prevention

• ⚡ Timeout Optimization - Smart pagination and limits

• 🧪 48KB Test Suite - Comprehensive testing and reporting

• 🎯 Performance Controls - Configurable timeouts and limits

📊 Quality Metrics:

• 1,158 lines of test coverage

• 13+ test categories including edge cases

• 90%+ success rate target for all operations

• Sub-5 second response times for optimized operations