mcpengine/servers/notion/README.md

Notion MCP Server

Model Context Protocol (MCP) server for the Notion API. Provides comprehensive access to Notion workspaces including pages, databases, blocks, users, comments, and search.

Features

• Pages: Create, read, update, and archive pages
• Databases: Query, create, and manage databases with advanced filtering and sorting
• Blocks: Retrieve, append, update, and delete blocks
• Users: Access workspace user information
• Comments: Create and retrieve comments on pages and blocks
• Search: Search across all pages and databases
• Rate Limiting: Built-in rate limiting (3 req/sec) with retry logic
• Pagination: Automatic cursor-based pagination support
• Type Safety: Comprehensive TypeScript types for the entire Notion API

Installation

npm install
npm run build

Configuration

Set the NOTION_API_KEY environment variable:

export NOTION_API_KEY="your_notion_integration_token"

Or create a .env file:

cp .env.example .env
# Edit .env and add your API key

Getting a Notion API Key

1. Go to https://www.notion.so/my-integrations
2. Click "+ New integration"
3. Give it a name and select the workspace
4. Copy the "Internal Integration Token"
5. Share your Notion pages/databases with the integration

Usage

Development

npm run dev

Production

npm start

With MCP Client

Add to your MCP settings configuration:

{
  "mcpServers": {
    "notion": {
      "command": "node",
      "args": ["/path/to/notion/dist/main.js"],
      "env": {
        "NOTION_API_KEY": "your_api_key_here"
      }
    }
  }
}

Available Tools

Pages

• notion_get_page - Retrieve a page by ID
• notion_create_page - Create a new page
• notion_update_page - Update page properties or archive

Databases

• notion_get_database - Get database schema and info
• notion_query_database - Query with filters and sorts
• notion_create_database - Create a new database

Blocks

• notion_get_block - Get a block by ID
• notion_get_block_children - Get child blocks
• notion_append_block_children - Add blocks to a parent
• notion_delete_block - Archive a block

Users

• notion_get_user - Get user info
• notion_list_users - List all workspace users

Comments

• notion_create_comment - Add a comment
• notion_list_comments - Get comments for a block

Search

• notion_search - Search pages and databases

Architecture

Type System (src/types/index.ts)

Comprehensive TypeScript definitions including:

• All block types as discriminated unions
• All property types (title, rich_text, number, select, etc.)
• User, Page, Database, Comment types
• Filter and Sort builders
• Pagination types
• Branded ID types for type safety

Client (src/clients/notion.ts)

Axios-based HTTP client with:

• Bearer token authentication
• Automatic rate limiting (3 req/sec)
• Exponential backoff retry logic
• Cursor-based pagination helpers
• Async generator support for large datasets

Server (src/server.ts)

MCP server implementation with:

• Lazy-loaded tool handlers
• Structured error handling
• JSON schema validation
• Comprehensive tool definitions

Entry Point (src/main.ts)

• Environment validation
• Stdio transport setup
• Graceful shutdown handling
• Error logging

Development

# Type check
npm run typecheck

# Build
npm run build

# Run in dev mode
npm run dev

License

MIT

Contributing

Contributions welcome! Please ensure:

• TypeScript compiles with zero errors
• Follow existing code style
• Add tests for new features
• Update documentation