Notion MCP Server

A production-grade Model Context Protocol (MCP) server for Notion, providing comprehensive database operations with schema validation and intelligent property handling.

Features

• 🔧 Full CRUD Operations - Create, read, update pages across Notion databases
• 🔍 Smart Search & Query - Powerful filtering and search capabilities
• 📊 Schema Management - Automatic schema fetching and validation
• 🎨 Content Formatting - Markdown ↔ Notion blocks conversion
• ⚡ Async Architecture - High-performance async operations
• 🛡️ Type Safety - Comprehensive property validation
• 🔄 API 2025-09-03 - Uses latest Notion API with data sources

Architecture

kas-fastmcp/
├── main.py                        # Entry point
├── config.py                      # NotionConfig, loads databases.yaml
├── notion_server/
│   ├── server.py                  # FastMCP("KasNotionMCP") instance
│   ├── deps.py                    # Shared NotionClient + SchemaManager singletons
│   ├── core/
│   │   ├── client.py              # NotionClient (httpx wrapper, 429 retry, connection pool)
│   │   ├── schema.py              # SchemaManager (10-min TTL, disk cache)
│   │   └── formatters.py          # PropertyFormatter, BlockFormatter (markdown <-> blocks)
│   ├── tools/
│   │   ├── query.py               # notion_query, notion_find_page_by_name, notion_search, notion_list_data_sources, notion_discover_databases
│   │   ├── pages.py               # notion_get_page, notion_get_data_source, notion_create_item, notion_update_item
│   │   ├── content.py             # notion_get_page_content, notion_append_content, notion_replace_content
│   │   └── schema_sync.py         # notion_sync_schemas, notion_validate_config
│   └── utils/
│       └── validators.py          # PropertyValidator
└── databases.yaml                 # Database configuration

Design Principles

1. Separation of Concerns - Core logic separated from MCP layer
2. No Circular Dependencies - Clean, linear dependency flow
3. Immutable Configuration - Config is never mutated at runtime
4. Schema-First - Validate against actual Notion schemas
5. Testable - Each layer can be tested independently

Installation

Prerequisites

• Python 3.10+
• Notion Integration with API access
• Notion databases with integration added

Setup

1. Clone the repository

git clone <your-repo-url>
cd kas-fastmcp

2. Install dependencies

uv sync

3. Configure environment

cp .env.example .env
# Edit .env and add your NOTION_TOKEN

4. Configure databases

cp databases.yaml.example databases.yaml
# Edit databases.yaml and add your database configurations

Getting Your Notion Credentials

1. Create Integration

   • Go to https://www.notion.so/my-integrations
   • Click "New integration"
   • Give it a name and select your workspace
   • Copy the "Internal Integration Token"

2. Get Data Source IDs

   • Open your database in Notion
   • Click "..." menu → Settings
   • Manage data sources → Copy data source ID
   • Add to databases.yaml

3. Add Integration to Databases

   • Open each database in Notion
   • Click "..." menu → Connections
   • Add your integration

Configuration

databases.yaml

Define all your Notion databases:

zettelkasten:
  data_source_id: "your-data-source-id-here"
  database_id: "your-database-id-here"
  title_property: "title"
  description: "Personal knowledge management"

habits:
  data_source_id: "your-data-source-id-here"
  database_id: "your-database-id-here"
  title_property: "title"
  description: "Habit tracking"

.env

NOTION_TOKEN=ntn_your_token_here
NOTION_API_VERSION=2025-09-03

Usage

Running the Server

Development:

python main.py

With FastMCP CLI:

fastmcp run main.py

Claude Desktop Integration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "kas-notion": {
      "command": "python",
      "args": ["/path/to/kas-fastmcp/main.py"]
    }
  }
}

Available Tools (15 total)

Query Tools (query.py)

• notion_query - Query pages from a database
• notion_find_page_by_name - Find page by exact title
• notion_search - Workspace-wide search
• notion_list_data_sources - List data sources for a database
• notion_discover_databases - Discover all accessible databases

Page Tools (pages.py)

• notion_get_page - Get page with properties (fully paginated when include_content=True)
• notion_get_data_source - Get database schema
• notion_create_item - Create new page
• notion_update_item - Update page properties

Content Tools (content.py)

• notion_get_page_content - Get page content as markdown
• notion_append_content - Append blocks to page
• notion_replace_content - Clear all blocks on a page and write new markdown content

Schema Tools (schema_sync.py)

• notion_sync_schemas - Sync schemas from Notion and optionally update config
• notion_validate_config - Validate current database configuration

Available Resources

• notion://databases - Lists all configured databases as JSON
• notion://databases/{source_name}/schema - Returns the cached schema for a specific database

Testing

Connection Testing

Quick token verification:

python connection_testing/token_verification.py

Full connection test:

python connection_testing/test_connection.py

This will:

• Validate your configuration
• Test API connectivity
• Check database access
• Fetch schemas

Validation Testing

Test the property validator directly:

python test_validation.py

Development

Adding a New Database

1. Add to databases.yaml:

my_database:
  data_source_id: "your-id"
  database_id: "your-id"
  title_property: "Name"
  description: "My new database"

2. No code changes needed! The server automatically loads all databases from the YAML file.

Adding a New Tool

1. Choose the appropriate module (query.py, pages.py, or content.py)
2. Use the @mcp.tool decorator
3. Import and use core modules
4. Document with clear docstrings

Example:

from notion_server.server import mcp
from notion_server.deps import _client  # shared singleton — do not instantiate a new one

@mcp.tool
async def my_new_tool(param: str) -> dict:
    """
    Tool description.

    Args:
        param: Parameter description

    Returns:
        Result description
    """
    result = await _client.get(f"endpoint/{param}")
    return result

Project Structure Explained

core/ - Pure business logic, no MCP dependencies

• Testable independently
• Reusable in other projects
• No side effects

tools/ - MCP tool definitions

• Thin wrappers around core modules
• Handle MCP-specific concerns
• Minimal business logic

utils/ - Shared utilities

• Validators
• Helpers
• Common functions

Validation System

How It Works

Properties are validated against Notion's schema before API calls:

# Automatic validation
notion_create_item(
    source_name="zettelkasten",
    properties={
        "title": {"title": [{"text": {"content": "My Note"}, "type": "text"}]},
        "nonexistent": {"rich_text": [...]}  # ❌ Validation error!
    }
)

What Gets Validated

✅ Property exists in schema
✅ Property type matches
✅ Select options are valid
✅ Read-only properties rejected
✅ Required properties present (strict mode)

Direct Validation

Use the validator directly in your code:

from notion_server.core import SchemaManager, NotionClient
from notion_server.utils import PropertyValidator

client = NotionClient()
schema_manager = SchemaManager(client)
schema = await schema_manager.get_schema("zettelkasten")

validator = PropertyValidator(schema)
is_valid, errors = validator.validate_properties(properties)

Troubleshooting

Common Issues

"NOTION_TOKEN not found"

• Create .env file from .env.example
• Add your token from https://www.notion.so/my-integrations

"Database not found (404)"

• Check database_id in databases.yaml
• Ensure integration is added to the database
• Verify integration has access

"No databases configured"

• Create databases.yaml from databases.yaml.example
• Add at least one database configuration

"Property validation failed"

• Check property names match your schema
• Ensure values are in correct Notion format
• Verify select options are valid

Debug Mode

Enable detailed logging by checking server output:

python main.py 2>&1 | tee server.log

API Reference

NotionClient

client = NotionClient(token=None, api_version=None)
await client.get(endpoint)
await client.post(endpoint, payload)
await client.patch(endpoint, payload)

SchemaManager

schema_manager = SchemaManager(client)
schema = await schema_manager.get_schema(source_name)
data_source_id = await schema_manager.get_data_source_id(source_name)
config = schema_manager.get_source_config(source_name)

PropertyFormatter

formatter = PropertyFormatter()
title = formatter.extract_title(properties)
formatted = formatter.format_for_display(properties)

BlockFormatter

formatter = BlockFormatter()
markdown = formatter.to_markdown(blocks)
blocks = formatter.from_markdown(markdown)

Contributing

Code Style

• Use type hints
• Write docstrings
• Keep functions focused
• Follow separation of concerns

Testing

• Test core modules independently
• Test tools through MCP protocol
• Validate against real Notion databases

License

MIT

Acknowledgments

• Built with FastMCP
• Uses Notion API 2025-09-03
• Developed for AI-powered productivity workflows

See CHANGELOG.md for version history.

Support

For issues, questions, or contributions, please open an issue on GitHub.

---

Built with ❤️ for AI-powered productivity