API-create-a-comment
Notion | Create comment Error Responses: 400: Bad request
LABSCO SUMMARY
Notion stops being the place work gets copied into by hand.
The two Markdown calls treat a page as text, so a document can be read, edited and written back without walking the block tree — and the range option means an edit can land in the middle of a long page. Everything structured is still there when the job needs it: data source queries, page properties, comments and the users behind them.
What it is
The Notion API as 24 tools: search, users, pages and their properties, blocks and their children, data sources and databases, comments, and two calls that read or write a page's whole content as Markdown.
What you get
- A search across the workspace by title, filtered and sorted, and any page, block or database retrieved by ID
- A page's content read as Markdown, and written back as Markdown — inserted, replaced whole, or replaced over a range
- Pages created under a parent with properties, icon and cover, updated, moved, or sent to the trash
- Blocks appended to a page, retrieved with their children, updated and deleted
- Data sources created, retrieved, updated and queried with filters and sorts, and their templates listed
- Comments read on a page or block, and new ones created
- Users listed or retrieved, and the bot user behind the token identified
Requirements
npx on your PATH and NOTION_TOKEN in the environment. The integration reaches only what has been shared with it, and the Markdown calls need its read and update content capability — without that they return 403.
Setup effort
One command plus a key — npx @notionhq/notion-mcp-server, then supply credentials
USE CASES
01
Turning notes into a written-up page
Find where it belongs, create the page under that parent, and write the body as Markdown in one call rather than block by block.
02
Pulling a status out of a Notion database
Query the data source with the filter and sort you would have clicked, and read the rows back as data instead of as a screenshot of a board.
03
Editing an existing doc without rebuilding it
Read the page as Markdown, change what needs changing, and write back only the range you touched. The rest of the page is left as it was.
04
Following up on comments left on a doc
Read the comments on the page or block, then reply where a reply is what is needed, without opening the workspace.
05
Reorganising where a page lives
Move the page under a different parent and update its properties, which is the tidy-up that otherwise happens by dragging things in a sidebar.
24 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
API-create-a-data-source
Notion | Create a data source Error Responses: 400: Bad request
API-delete-a-block
Notion | Delete a block Error Responses: 400: Bad request
API-get-block-children
Notion | Retrieve block children Error Responses: 400: Bad request
API-get-self
Notion | Retrieve your token's bot user Error Responses: 400: Bad request
API-get-user
Notion | Retrieve a user Error Responses: 400: 400
API-get-users
Notion | List all users Error Responses: 400: 400
API-list-data-source-templates
Notion | List templates in a data source Error Responses: 400: Bad request
API-move-page
Notion | Move a page Error Responses: 400: Bad request
API-patch-block-children
Notion | Append block children Error Responses: 400: Bad request
API-patch-page
Notion | Update page properties Error Responses: 400: Bad request
API-post-page
Notion | Create a page Error Responses: 400: Bad request
API-post-search
Notion | Search by title Error Responses: 400: Bad request
API-query-data-source
Notion | Query a data source Error Responses: 400: Bad request
API-retrieve-a-block
Notion | Retrieve a block Error Responses: 400: Bad request
API-retrieve-a-comment
Notion | Retrieve comments Error Responses: 400: Bad request
API-retrieve-a-data-source
Notion | Retrieve a data source Error Responses: 400: Bad request
API-retrieve-a-database
Notion | Retrieve a database Error Responses: 400: Bad request
API-retrieve-a-page
Notion | Retrieve a page Error Responses: 400: Bad request
API-retrieve-a-page-property
Notion | Retrieve a page property item Error Responses: 400: Bad request
API-retrieve-page-markdown
Notion | Retrieve a page as Markdown Error Responses: 400: Bad request 403: The integration lacks the read/update content capability required for this page. 404: Page not found or not shared with the integration. 429: Rate limited.
API-update-a-block
Notion | Update a block Error Responses: 400: Bad request
API-update-a-data-source
Notion | Update a data source Error Responses: 400: Bad request
API-update-page-markdown
Notion | Update a page's content as Markdown Error Responses: 400: Bad request 403: The integration lacks the read/update content capability required for this page. 404: Page not found or not shared with the integration. 409: Conflict (e.g. row limit exceeded). 429: Rate limited.
BEFORE YOU INSTALL
What to know first
Tools you get
24 tools when we connected. Every tool name carries an API- prefix (API-move-page), so bare names from the documentation will not resolve. post-database-query, update-a-database and create-a-database were removed. Your integration's Notion capabilities and connected pages decide what works.
Requires
- npx on PATH
- NOTION_TOKEN in your environment
Where it runs
All 7 documented setups run the server on your machine.
CONTEXT COST
Heavy Standing cost
Rated by the size of the 24 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
Connect your client
Server setup
TERMINAL
npx @notionhq/notion-mcp-serverMCP Clients
Cursor — token, Claude Desktop — token, GitHub Copilot — token
JSON
{
"mcpServers": {
"notionApi": {
"command": "npx",
"args": [
"-y",
"@notionhq/notion-mcp-server"
],
"env": {
"NOTION_TOKEN": "<YOUR_NOTION_TOKEN>"
}
}
}
}Cursor — auth header, Claude Desktop — auth header
JSON
{
"mcpServers": {
"notionApi": {
"command": "npx",
"args": [
"-y",
"@notionhq/notion-mcp-server"
],
"env": {
"OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2025-09-03\" }"
}
}
}
}Zed
ZED · JSON
{
"context_servers": {
"some-context-server": {
"command": {
"path": "npx",
"args": [
"-y",
"@notionhq/notion-mcp-server"
],
"env": {
"OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2025-09-03\" }"
}
},
"settings": {}
}
}
}Any MCP client — Docker Hub
ANY MCP CLIENT — DOCKER HUB · JSON
{
"mcpServers": {
"notionApi": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"NOTION_TOKEN",
"mcp/notion"
],
"env": {
"NOTION_TOKEN": "<YOUR_NOTION_TOKEN>"
}
}
}
}
