notion-mcp-server
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| NOTION_TOKEN | Yes | Your Notion API key from Notion Developers | |
| NOTION_PAGE_ID | Yes | The ID of your Notion page where the integration is enabled |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Notion MCP server. notion_read(operation, payload) runs one read operation and notion_write(operation, payload) one write operation; each tool's operation enum is its complete menu. notion_describe(operation) returns an operation's JSON Schema and a working example; the notion://operations resource lists every operation with a one-line summary.
How to work:
Find things with search_pages (title search across pages and databases) or query_database. Results are slimmed to id, title, url and a few fields. Every id field also accepts a Notion URL, so paste links as-is.
Read a page with get_page_markdown for prose, or get_page with include_properties:true for a database row's fields.
Write prose as markdown: create_page and append_blocks take a
markdownfield (GFM: headings, lists, checkboxes, tables, code). Use rawchildrenblocks only for what markdown cannot express.A database has one or more data sources. query_database resolves single-source databases itself and filters with where { Status: "Done" }; to create a row use parent { type: "data_source_id", data_source_id } from search results or list_data_sources. Row properties take plain values: { Status: "Done", Due: "2026-01-01", Tags: ["a"] }.
Batchable operations take payload { items: [...], atomic?, concurrency?, idempotency_key? } and run in one call with per-item results.
Errors carry code, message and fix plus the slice of the schema you got wrong: correct and retry. A result's warnings list fields that were ignored. Call notion_describe only for complex shapes (property definitions, block trees).
Archive and delete operations cannot be undone through the API; confirm with the user before running them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| logging | {} |
| prompts | {
"listChanged": true
} |
| resources | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| notion_readA | Run one Notion read operation by name. Nothing is modified. Call: { operation, payload } — payload carries that operation's fields. Common: search_pages { query }, get_page { page_id }, get_page_markdown { page_id }, query_database { database_id, where? }, get_block_children { block_id }. Responses are slimmed; pass verbose:true in payload for the raw Notion object. Every id field (page_id, block_id, database_id, view_id, …) also accepts a Notion URL, as copied from Share → Copy link. A block link's #fragment is used for block_id fields and a database link's ?v= for view_id fields. If the payload is malformed, the error response includes the schema + a working example so you can correct and retry in one round-trip. Call notion_describe(operation) ahead of time only for complex shapes (query_database filters). |
| notion_writeA | Run one Notion write operation by name. Archive, trash and delete operations remove content — confirm with the user before running them. Two ways to call: • Single: { operation: "set_page_title", payload: { page_id, title } } • Batch: { operation: "set_page_title", payload: { items: [{page_id, title}, ...], atomic?: false, idempotency_key?: "...", concurrency?: 3 } } create_page, append_blocks, update_block and update_page_markdown also take a markdown string. Responses are slimmed; pass verbose:true inside payload (single) or per item (batch) for the raw Notion object. Every id field (page_id, block_id, database_id, view_id, …) also accepts a Notion URL, as copied from Share → Copy link. If the payload is malformed, the error response includes the schema + a working example so you can correct and retry in one round-trip. Call notion_describe(operation) ahead of time only for complex shapes (block trees, database property definitions, batch_mixed_blocks). |
| notion_describeA | Return the JSON Schema and a working example for one operation, plus which tool runs it (notion_read or notion_write). Use this BEFORE calling the operation when the payload shape is non-trivial (query filters, structured block trees, database property definitions). For simple ops, just call it — errors carry the schema. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| create_task | Create a new task page in Notion with optional status and due date. |
| weekly_review | Summarize tasks marked Done in the last 7 days from a Notion database. |
| find_pages | Search Notion and show the top 5 matching pages. |
| daily_log | Append a timestamped paragraph to a daily-log page in Notion. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| operations-index | Markdown table of every supported operation, batchability, and one-line description. |
TDQS
Scored across 3 tools
The three tools have clearly distinct purposes: notion_read executes non-modifying operations, notion_write executes mutating operations, and notion_describe returns schemas/examples without executing anything. An agent can easily select among them based on intent, and the descriptions reinforce the boundaries.
All tool names follow the same predictable pattern: notion_ + verb (read, write, describe), all in snake_case. There are no naming style deviations or confusing abbreviations.
Three tools is well-scoped for a facade-style server that multiplexes many Notion operations. Each tool earns its place: read, write, and schema discovery cover the necessary interaction modes without unnecessary proliferation.
The surface covers core page, block, and database read/write operations, including search, markdown conversion, batch writes, and lifecycle operations like archive/trash. Minor gaps may exist for peripheral Notion domains such as comments, users, or database schema management, but the main workflows are well supported.