Notion Integration Documentation

Overview

Piper Morgan’s Notion integration provides seamless knowledge management through MCP+Spatial Intelligence architecture, enabling natural interaction with your Notion workspace.

Configuration

Prerequisites

  1. Create Notion Integration

    • Go to Notion Integrations
    • Create a new integration
    • Copy the Internal Integration Token (starts with secret_)

  2. Environment Setup

    # Add to .env file
NOTION_API_KEY=secret_your_integration_token
NOTION_WORKSPACE_ID=your_workspace_id  # Optional

  3. Grant Access

    • In Notion, share pages/databases with your integration
    • Use the integration name when sharing

CLI Commands

Check Integration Status

python cli/commands/notion.py status

Shows configuration status, connection state, and setup instructions.

Test Connection

python cli/commands/notion.py test

Validates API key and tests live connection to Notion workspace.

Search Workspace

python cli/commands/notion.py search --query "project requirements"

Search across your Notion workspace for relevant content.

List Recent Pages

python cli/commands/notion.py pages

Display up to 20 pages from your Notion workspace with titles, IDs, and URLs.

Create New Page

python cli/commands/notion.py create "Page Title"

Create a new page with the specified title. Optionally specify a parent page:

python cli/commands/notion.py create "Page Title" --parent-id "parent-page-id"

If no parent is specified, the system will automatically select the first available page as the parent.

Architecture

Components

  1. NotionMCPAdapter (services/integrations/mcp/notion_adapter.py)

    • MCP spatial adapter for Notion API
    • 544 lines of comprehensive integration
    • Handles authentication, API calls, rate limiting
    • Key methods: connect(), get_current_user(), search(), create_page(), get_page(), list_pages()

  2. NotionSpatialIntelligence (services/intelligence/spatial/notion_spatial.py)

    • 8-dimensional spatial analysis
    • 631 lines of intelligence mapping
    • Analyzes page relationships and context

  3. NotionCanonicalQueryEngine (services/features/notion_queries.py)

    • Enhances canonical queries with Notion context
    • Performance target: <200ms (actual: 0.1ms)
    • Graceful degradation when unconfigured

  4. NotionConfig (config/notion_config.py)

    • Environment-based configuration
    • Validation and status reporting
    • Zero-config graceful degradation

Integration Pattern

# Automatic enhancement of queries with Notion context
from services.features.notion_queries import enhance_with_notion_intelligence

result = await enhance_with_notion_intelligence(
    intent=user_intent,
    session_id=session.id,
    canonical_handlers=handlers
)

Performance

Testing

Test Coverage

Running Tests

# Run Notion integration tests
PYTHONPATH=. python -m pytest tests/features/test_notion_integration.py -v
PYTHONPATH=. python -m pytest tests/features/test_notion_spatial_integration.py -v

End-to-End Testing

The CLI supports full CRUD operations for comprehensive testing:

# Full CRUD cycle test
python cli/commands/notion.py status          # Verify connection
python cli/commands/notion.py pages           # List existing pages
python cli/commands/notion.py search --query "test"  # Search content
python cli/commands/notion.py create "Test Page"     # Create new page
python cli/commands/notion.py search --query "Test Page"  # Verify creation

Troubleshooting

Common Issues

  1. “NOTION_API_KEY not set”

    • Add your Notion API key to .env
    • Ensure key starts with secret_

  2. “Connection test failed”

    • Verify API key is correct
    • Check internet connectivity
    • Ensure integration has workspace access

  3. “No pages found”

    • Share pages with your integration in Notion
    • Wait a few minutes for permissions to propagate

  4. “Failed to create page”

    • Ensure the integration has write permissions
    • Verify the parent page ID is valid
    • Check that the integration has access to the parent page

Current Status

The Notion integration is fully functional with complete CRUD operations:

API Version 2025-09-03 Upgrade

Status: ✅ Complete (October 15, 2025)

Piper Morgan’s Notion integration has been upgraded to Notion API version 2025-09-03, which introduces important changes to how databases and data sources are handled.

What Changed

Notion API 2025-09-03 separates the concepts of “databases” and “data sources”:

This enables databases to combine multiple data sources, but requires using data_source_id instead of database_id for certain operations.

Automatic Handling (No User Action Required)

Good news: The upgrade is completely automatic! The integration handles data_source_id behind the scenes:

  1. Dynamic Fetching: When creating pages in databases, the integration automatically:
    • Fetches the data_source_id from the database metadata
    • Uses it for API calls that require it
    • Falls back to database_id format for backward compatibility
  2. Backward Compatibility: The integration works with:
    • ✅ Databases on API 2025-09-03 (using data_source_id)
    • ✅ Databases not yet migrated (using database_id)
    • ✅ Single-source databases (most common case)
    • ✅ Multi-source databases (uses primary source)
  3. Zero Configuration: No changes needed to your:
    • Environment variables
    • PIPER.user.md configuration
    • Existing workflows or commands

Technical Details

SDK Version: notion-client==2.5.0 (upgraded from 2.2.1)

API Version Header: All requests include Notion-Version: 2025-09-03

Implementation:

For more details, see:

Verification

To verify the upgrade is working:

# Check SDK version
pip show notion-client
# Should show: Version: 2.5.0

# Test database operations
python cli/commands/notion.py test
# Should succeed with no errors

Future Enhancements

Support

For issues or questions: