Skip to main content
Glama

Notion MCP Server V2

by ankitmalik84
GitHub
Python
1
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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

notion_mcp_server/ ├── 📄 __init__.py # Package initialization ├── 🔧 config.py # Configuration management ├── 🌐 api_serverV2.py # FastAPI REST API server (49KB) ├── 💻 serverV2.py # Interactive CLI server ├── ⚙️ core_operations.py # Basic CRUD operations ├── 📊 analytics_operations.py # Analytics and metrics ├── 🔄 bulk_operations.py # Bulk processing ├── ✏️ update_operations.py # Content updates (35KB) ├── 🛠️ notion_utils.py # Utility functions ├── 🧪 test_server.py # Comprehensive test suite (48KB) └── 📖 README.md # This file

📦 Installation

Prerequisites

  • Python 3.8+

  • Notion account with integration token

  • pip or conda package manager

Setup

  1. Install Dependencies

pip install notion-client fastapi uvicorn python-dotenv pydantic requests

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

# Required NOTION_TOKEN=ntn_your_integration_token_here # Optional Server Settings HOST=0.0.0.0 PORT=8081 DEBUG=false # Optional Feature Settings MAX_PAGE_SIZE=100 DEFAULT_PAGE_SIZE=20 MAX_CONTENT_LENGTH=2000 ENABLE_ANALYTICS=true ENABLE_BULK_OPERATIONS=true # Optional Logging LOG_LEVEL=INFO

  1. 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:

python -m notion_mcp_server.api_serverV2

Server will be available at:

  • API: http://localhost:8081

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

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

2. Interactive CLI

python -m notion_mcp_server.serverV2

3. Python Integration

from notion_mcp_server import ComprehensiveNotionServer import asyncio async def example(): server = ComprehensiveNotionServer("your_notion_token") await server.core_ops.search_content("search term") asyncio.run(example())

📚 API Documentation

🔍 Search Endpoint

POST /api/search Content-Type: application/json { "query": "search term", "page_size": 10 }

📄 Create Page

POST /api/page/create Content-Type: application/json { "title": "My New Page", "content": "Initial content", "parent_id": "optional-parent-page-id" }

📖 Read Page

POST /api/page/read Content-Type: application/json { "identifier": "page-id-or-title" }

✏️ Add Content (ENHANCED)

POST /api/page/add-content Content-Type: application/json { "page_id": "page-id", "content_type": "paragraph", "content": "New paragraph content" }

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):

POST /api/page/add-content Content-Type: application/json { "page_id": "page-id", "content_type": "bookmark", "content": "OpenAI Website", "url": "https://www.openai.com" }

Add Link to Page (Internal Link):

POST /api/page/add-content Content-Type: application/json { "page_id": "page-id", "content_type": "link_to_page", "content": "Link to related page", "page_reference": "target-page-id-or-title" }

🔄 Bulk Content Addition (ENHANCED)

POST /api/page/bulk-add-content Content-Type: application/json { "page_id": "page-id", "items": [ { "content_type": "heading_2", "content": "Section Title" }, { "content_type": "paragraph", "content": "Paragraph content" }, { "content_type": "bookmark", "url": "https://example.com", "content": "External Link" }, { "content_type": "link_to_page", "page_reference": "other-page-id", "content": "Internal Link" }, { "content_type": "to_do", "content": "Task item", "checked": false } ] }

📊 Analytics

POST /api/analytics Content-Type: application/json { "type": "workspace" }

Analytics types: workspace, content, activity, database

🔄 Bulk Operations (OPTIMIZED)

POST /api/bulk Content-Type: application/json { "operation": "list", "query": "{\"limit\": 10, \"include_block_counts\": false}" }

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

POST /api/agent/query Content-Type: application/json { "action": "search", "parameters": { "query": "search term", "page_size": 10 } }

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

🧪 Testing (COMPREHENSIVE)

Run the comprehensive test suite:

# Start the server first python -m notion_mcp_server.api_serverV2 # In another terminal, run tests cd src/notion_mcp_server python test_server.py

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

Variable

Default

Description

NOTION_TOKEN

(required)

Your Notion integration token

HOST

0.0.0.0

Server host address

PORT

8081

Server port

DEBUG

false

Enable debug mode

MAX_PAGE_SIZE

100

Maximum results per page

DEFAULT_PAGE_SIZE

20

Default results per page

MAX_CONTENT_LENGTH

2000

Maximum content block length

ENABLE_ANALYTICS

true

Enable analytics endpoints

ENABLE_BULK_OPERATIONS

true

Enable bulk operations

LOG_LEVEL

INFO

Logging level

Configuration Validation

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

🔧 Integration Examples

With AI Agents

import requests # Search for content response = requests.post("http://localhost:8081/api/agent/query", json={ "action": "search", "parameters": {"query": "project notes"} }) # Create a new page with links response = requests.post("http://localhost:8081/api/agent/query", json={ "action": "create_page", "parameters": { "title": "AI Generated Page", "content": "This page was created by an AI agent" } }) # Add bookmark to page response = requests.post("http://localhost:8081/api/agent/query", json={ "action": "add_content", "parameters": { "page_id": "page-id", "content_type": "bookmark", "content": "Useful Resource", "url": "https://example.com" } })

With Your Chatbot

# Already integrated in your chatbot_agentic_v3.py! # Enhanced with ALL new functions: # Core functions server.notion_search_content() server.notion_read_page() server.notion_create_page() # Content addition with links server.notion_add_paragraph() server.notion_add_heading() server.notion_add_bullet_point() server.notion_add_todo() # Smart content helpers server.notion_add_structured_content() # Multi-section content server.notion_add_smart_content() # AI-friendly content parsing # Bulk operations server.notion_bulk_create_pages() server.notion_bulk_list_pages() server.notion_bulk_analyze_pages() # Analytics server.notion_workspace_analytics() server.notion_content_analytics() server.notion_activity_analytics()

📈 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:

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

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

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

  1. ✨ Features
    1. 🔧 Core Operations
    2. 🔗 Advanced Content Types (NEW)
    3. 📊 Analytics & Insights
    4. 🔄 Bulk Operations (OPTIMIZED)
    5. 🌐 API Interfaces
    6. 🛡️ Production Features (ENHANCED)
    7. 🧪 Testing & Quality (COMPREHENSIVE)
  2. 🏗️ Architecture
    1. 📦 Installation
      1. Prerequisites
      2. Setup
    2. 🚀 Usage
      1. 1. FastAPI Server (Production)
      2. 2. Interactive CLI
      3. 3. Python Integration
    3. 📚 API Documentation
      1. 🔍 Search Endpoint
      2. 📄 Create Page
      3. 📖 Read Page
      4. ✏️ Add Content (ENHANCED)
      5. 🔗 Link Content Types (NEW)
      6. 🔄 Bulk Content Addition (ENHANCED)
      7. 📊 Analytics
      8. 🔄 Bulk Operations (OPTIMIZED)
      9. 🤖 Agent Integration
    4. 🧪 Testing (COMPREHENSIVE)
      1. ⚙️ Configuration
        1. Environment Variables
        2. Configuration Validation
      2. 🔧 Integration Examples
        1. With AI Agents
        2. With Your Chatbot
      3. 📈 Performance Features (ENHANCED)
        1. 🛡️ Security & Validation Features (BULLETPROOF)
          1. 📋 Error Handling (ENHANCED)
            1. Validation Errors
            2. API Errors
            3. HTTP Status Codes
          2. 🆔 Version History
            1. V2.1.0 (Current) (MAJOR UPDATE)
            2. V2.0.0 (Previous)
            3. V1.0.0 (Legacy)
          3. 🤝 Contributing
            1. 📞 Support
              1. 📧 Contact Information
            2. 📄 License

              Related MCP Servers

              • SystemPrompt MCP Notion Server

                Ejb503
                A
                security
                F
                license
                A
                quality
                A high-performance MCP server that integrates Notion into AI workflows, enabling interaction with Notion pages, databases, and comments through a standardized protocol.
                Last updated -
                12
                24

              • Notion MCP Server

                ccabanillas
                -
                security
                A
                license
                -
                quality
                A Model Context Protocol server that provides a standardized interface for interacting with Notion's API, enabling users to list databases, create pages, and search across their Notion workspace.
                Last updated -
                109
                MIT License
                • Apple

              • Notion MCP Server

                ramidecodes
                A
                security
                A
                license
                A
                quality
                A Model Context Protocol (MCP) server that exposes the official Notion SDK, allowing AI models to interact with Notion workspaces.
                Last updated -
                76
                8
                Apache 2.0
                • Apple
                • Linux

              • AgentModeofficial

                agentmode
                A
                security
                F
                license
                A
                quality
                An all-in-one Model Context Protocol (MCP) server that connects your coding AI to numerous databases, data warehouses, data pipelines, and cloud services, streamlining development workflow through seamless integrations.
                Last updated -
                3
                • Apple
                • Linux

              View all related MCP servers

              New MCP Servers

              MCP directory API

              We provide all the information about MCP servers via our MCP API.

              curl -X GET 'https://glama.ai/api/mcp/v1/servers/ankitmalik84/Agentic_Longterm_Memory'

              If you have feedback or need assistance with the MCP directory API, please join our Discord server