The most comprehensive MCP server for Notion - Pages, Databases, Blocks, Users, Comments & Search
This Notion MCP server has 15 well-named tools with complete input schemas and consistent descriptions. Naming follows verb_noun convention (notion_search_pages, notion_create_page, notion_update_block) and is action-clear. All tools have descriptions (194 chars baseline met). However, several critical issues prevent a higher score: (1) Output schemas are completely undocumented, no tool specifies what fields are returned, their types, or how to chain results. (2) Error handling is absent, no guidance on retryability, user-fixable errors, or recovery steps. (3) Parameter descriptions lack detail on constraints (e.g., page_size accepts 1-100 but this is not stated in the description text itself, only in the schema). (4) No pagination guidance despite tools like notion_query_database returning result sets. (5) Security: the server accepts NOTION_API_KEY as an environment variable (correct), but the code does not validate API errors or handle credential-related failures gracefully. (6) Composition: tools are properly single-purpose and chainable (e.g., notion_search_pages returns page IDs that notion_get_page accepts), but responses are not verified to include downstream reference IDs.
Append new blocks to a page or block. Supports all block types: paragraph, heading, list, code, etc.
Archive (soft-delete) a page. The page can be restored later.
Create a new database as a child of a page. Define custom properties/schema.
Create a new page in a database or as a child of another page. Supports rich properties.
Delete (archive) a block. This removes it from the page.
Get a specific block by ID.
No output schemas documented. Every tool lacks return type documentation, no field names, types, structure, or examples. LLMs cannot know what data is available downstream or which fields to extract for chaining.
No error handling or recovery guidance. Tools fail silently or return raw API errors with no actionable guidance. No distinction between retryable errors (timeout), user-fixable errors (invalid parent_id), or fatal errors (permission denied).
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | D | 58 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 0 | - | v1 |
Get all child blocks of a block or page. Supports pagination for large pages.
Get database schema including all properties and their types.
Get a specific page by ID. Returns full page properties and metadata.
Query a database with optional filters, sorts, and pagination. Powerful filtering support.
Restore an archived page.
Search for pages in Notion by title. Returns matching pages with their IDs and properties.
Update a block's content. The update object depends on block type.
Update database title, description, or properties schema.
Update page properties, icon, cover, or archive status.
Parameter constraints not documented in descriptions. Tools mention 'page_size (max 100)' in schema but not in the description text itself. Per the rubric, LLMs rely on description text, not raw schema, they may not read JSON Schema bounds. Descriptions should state: 'page_size: Number of results (1-100, default 10)'.
Pagination not documented. notion_query_database and notion_get_block_children accept start_cursor but descriptions do not explain pagination workflow: when to use start_cursor, what the next result looks like, or how to detect the end of results.
Irreversible operations lack confirmation/dry-run support. notion_delete_block, notion_archive_page, and other destructive tools do not offer a confirmation step or dry-run mode. Agents can accidentally delete content without safeguards.
Complex parameter types under-documented. notion_create_page accepts 'children' (array of block objects), 'properties' (object with Notion property definitions), and 'icon'/'cover' (objects). Descriptions say 'Optional array of block objects' and 'Optional cover image' but do not explain required structure, valid keys, or formats. LLMs will guess at structure and fail.
No output chaining verification. Tools like notion_search_pages likely return page IDs, but this is not documented. Downstream tools (notion_get_page, notion_update_page, notion_create_database) accept these IDs, but the response is not verified to include the correct reference field names. If the API returns 'id' but the tool description says 'page_id', the chain breaks.
No result limits specified. Tools returning multiple results (notion_search_pages, notion_query_database) may return hundreds or thousands of items. No description states a default limit or maximum to prevent context explosion.