easy-notion-mcp-integration

# Easy Notion MCP Integration > Skill by [ara.so](https://ara.so) — MCP Skills collection. ## Overview `easy-notion-mcp` is a production-grade Model Context Protocol (MCP) server that bridges AI agents to Notion using GitHub-flavored markdown instead of raw Notion API JSON. It provides 42 MCP tools for reading and writing Notion content with round-trip fidelity across 24 block types including toggles, columns, callouts, tables, and file uploads. ### Key Features - **Markdown-first I/O**: Agents work with markdown; server handles all Notion block JSON conversion - **Database ergonomics**: Write simple property objects like `{ "Status": "Done" }` with automatic schema mapping - **Dual transport**: Stdio (API token) or HTTP (OAuth/bearer token) - **Optional Redis**: Shared schema cache and OAuth persistence for multi-instance deployments - **Security defaults**: Content sanitization, URL validation, workspace-root file containment ## Installation ### Quick Start with npx (Recommended) Configure in your MCP client (Claude Desktop, Cursor, etc.): ```json { "mcpServers": { "notion": { "command": "npx", "args": ["-y", "easy-notion-mcp"], "env": { "NOTION_TOKEN": "YOUR_NOTION_INTEGRATION_TOKEN" } } } } ``` ### From Source ```bash git clone https://github.com/Grey-Iris/easy-notion-mcp.git cd easy-notion-mcp npm install npm run build ``` MCP client configuration: ```json { "mcpServers": { "notion": { "command": "node", "args": ["/absolute/path/to/easy-notion-mcp/dist/index.js"], "env": { "NOTION_TOKEN": "YOUR_NOTION_INTEGRATION_TOKEN", "NOTION_ROOT_PAGE_ID": "optional_default_parent_page_id" } } } } ``` ### Getting a Notion Integration Token 1. Visit https://www.notion.so/my-integrations 2. Click **+ New integration** 3. Name your integration and select capabilities 4. Copy the **Internal Integration Token** (starts with `ntn_`) 5. Share target pages/databases with your integration ## Configuration ### Environment Variables **Core Settings:** ```bash # Required for stdio transport NOTION_TOKEN=ntn_your_integration_token_here # Optional: default parent for create_page NOTION_ROOT_PAGE_ID=abc123def456 # Disable content-notice prefix on reads (default: false) NOTION_TRUST_CONTENT=false # Root directory for file:// uploads (default: cwd) NOTION_MCP_WORKSPACE_ROOT=/path/to/workspace # Logging verbosity: debug, info, warn, error (default: info) LOG_LEVEL=info ``` **HTTP Transport (OAuth or Static Bearer):** ```bash # Static bearer token for /mcp endpoint NOTION_MCP_BEARER=your_random_secret_token # OAuth configuration NOTION_OAUTH_CLIENT_ID=your_oauth_client_id NOTION_OAUTH_CLIENT_SECRET=your_oauth_client_secret # HTTP server settings PORT=3333 NOTION_MCP_BIND_HOST=127.0.0.1 ``` **Redis (Optional Multi-Instance Persistence):** ```bash # Enable Redis (auto-enabled if REDIS_URL is set) REDIS_ENABLED=true REDIS_URL=redis://127.0.0.1:6379/0 # Or configure individually: REDIS_HOST=127.0.0.1 REDIS_PORT=6379 REDIS_PASSWORD=your_redis_password REDIS_DB=0 REDIS_KEY_PREFIX=easy-notion: REDIS_CONNECT_TIMEOUT_MS=10000 REDIS_MAX_RETRIES=3 ``` ### .env File Setup ```bash cp .env.example .env # Edit .env with your configuration ``` ## MCP Tools Reference ### Page Operations #### `read_page` Read a Notion page as markdown. ```typescript // Tool call { "name": "read_page", "arguments": { "page_id": "abc123def456" } } // Response includes markdown with metadata { "markdown": "# Page Title\n\nContent here...", "warnings": [] } ``` #### `create_page` Create a new page with markdown content. ```typescript { "name": "create_page", "arguments": { "title": "My New Page", "markdown": "# Heading\n\nSome **bold** text.", "parent_page_id": "parent123" // optional, uses NOTION_ROOT_PAGE_ID if not set } } // Response { "id": "new_page_id", "url": "https://notion.so/...", "title": "My New Page" } ``` #### `update_page` Update page content with markdown. ```typescript { "name": "update_page", "arguments": { "page_id": "abc123", "markdown": "# Updated Content\n\nNew paragraph.", "mode": "replace" // or "append" } } ``` #### `append_to_page` Append markdown to existing page. ```typescript { "name": "append_to_page", "arguments": { "page_id": "abc123", "markdown": "\n## New Section\n\nAppended content." } } ``` #### `delete_page` Move page to trash. ```typescript { "name": "delete_page", "arguments": { "page_id": "abc123" } } ``` ### Database Operations #### `query_database` Query database with filters and sorts. ```typescript { "name": "query_database", "arguments": { "database_id": "db123", "filter": { "property": "Status", "select": { "equals": "In Progress" } }, "sorts": [ { "property": "Created", "direction": "descending" } ], "page_size": 50 } } // Returns array of entries with markdown content { "results": [ { "id": "entry123", "properties": { "Status": "In Progress", "Name": "Task 1" }, "markdown": "Task content..." } ], "has_more": false } ``` #### `get_database` Get database schema and properties. ```typescript { "name": "get_database", "arguments": { "database_id": "db123" } } // Returns schema information { "id": "db123", "title": "Tasks", "properties": { "Name": { "type": "title" }, "Status": { "type": "select", "options": ["To Do", "In Progress", "Done"] }, "Due Date": { "type": "date" } } } ``` #### `add_database_entry` Create new database entry with automatic schema conversion. ```typescript { "name": "add_database_entry", "arguments": { "database_id": "db123", "properties": { "Name": "New Task", "Status": "To Do", "Due Date": "2026-12-31", "Tags": ["urgent", "bug"] }, "markdown": "## Task Details\n\nDetailed description here." } } // Response { "id": "new_entry_id", "url": "https://notion.so/...", "properties": { /* converted properties */ } } ``` #### `update_database_entry` Update database entry properties and/or content. ```typescript { "name": "update_database_entry", "arguments": { "page_id": "entry123", "properties": { "Status": "Done", "Completed": true }, "markdown": "Updated task description." } } ``` ### Search Operations #### `search_notion` Full-text search across workspace. ```typescript { "name": "search_notion", "arguments": { "query": "project planning", "filter": { "property": "object", "value": "page" }, "sort": { "direction": "descending", "timestamp": "last_edited_time" }, "page_size": 20 } } // Returns matching pages/databases { "results": [ { "id": "page123", "title": "Q4 Project Planning", "url": "https://notion.so/...", "last_edited_time": "2026-07-03T10:30:00Z" } ], "has_more": false } ``` ### File Operations #### `upload_file` Upload local file to a page (stdio transport only). ```typescript { "name": "upload_file", "arguments": { "page_id": "abc123", "file_path": "/workspace/documents/report.pdf", "caption": "Q3 Financial Report" } } // Security: file_path must be within NOTION_MCP_WORKSPACE_ROOT ``` #### `add_image` Add image from URL to page. ```typescript { "name": "add_image", "arguments": { "page_id": "abc123", "url": "https://example.com/image.png", "caption": "Architecture Diagram" } } ``` ### Block Operations #### `create_block` Create specific block types. ```typescript // Callout block { "name": "create_block", "arguments": { "parent_id": "page123", "type": "callout", "content": { "icon": "💡", "text": "Important note here", "color": "blue_background" } } } // Toggle block { "name": "create_block", "arguments": { "parent_id": "page123", "type": "toggle", "content": { "text": "Click to expand", "children": [ { "type": "paragraph", "text": "Hidden content" } ] } } } ``` ## Common Patterns ### Reading and Updating a Page ```typescript // 1. Read existing page const readResponse = await callTool("read_page", { page_id: "abc123def456" }); // 2. Process markdown const existingMarkdown = readResponse.markdown; const updatedMarkdown = existingMarkdown + "\n## New Section\n\nAdded content."; // 3. Update page