MCP SERVERReach 43 Notion operations through two tools: name the operation and hand it a payload, singly or as a batch with an idempotency key, and ask for the schema whenever the payload shape is not obvious.
LABSCO SUMMARY
The trade is explicit: you carry two definitions instead of dozens, and in exchange the catalogue is not readable from the tool list — you find it through the describe tool, the operations resource, and the schema attached to an error. Batching is where the shape pays off, since one call can update a list of items with an idempotency key and a concurrency setting rather than issuing them one at a time. Before pointing it at a real workspace, decide what it may do: read-only is one environment variable, and the operation allow list is the finer-grained version of the same control.
A server that puts Notion behind two tools — an executor that takes an operation name and a payload, and a describe tool that returns the JSON Schema and a worked example for one operation. It authenticates with a token rather than OAuth, so it runs unattended.
A Notion token in NOTION_TOKEN: a personal access token, which sees everything you can see and expires a year after creation, or an internal integration secret, which only sees pages you have explicitly connected it to — most "could not find" errors are that second case. NOTION_PAGE_ID sets a default parent for new pages. It runs over stdio from npx or the published Docker image; an HTTP mode exists and is single-tenant, so everyone reaching it acts as that one token — bind it to loopback or put an auth token in front of it. MIT.
One command plus a key — npx -y notion-mcp-server, then supply credentials
USE CASES
The batch form takes the items as a list and adds the arguments that make a bulk write safe to retry: whether it is atomic, an idempotency key, and how many run at once.
Query filters, structured block trees and database property definitions are the shapes worth checking before sending. Ask for the schema and the example first, then execute against it.
Read the page as markdown, let the model edit the text, and write the markdown back — no block tree to assemble by hand.
Query with a typed filter and get rows back as flat name-to-value maps, which is far less to read than Notion's raw property structure.
Start the server read-only, or allow only the read group, and every mutating operation disappears from the catalogue and is refused if called.
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
notion_describeReturn the JSON Schema and a working example for one operation. Use this BEFORE notion_execute when the payload shape is non-trivial (query filters, structured block trees, database property definitions). For simple ops, just call notion_execute — its errors carry the schema.
notion_executeExecute a Notion operation by name.
Two ways to call:
If the payload is malformed, the error response includes the full 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, batch_mixed_blocks).
Most responses are slimmed by default. Pass verbose:true inside payload (single) or per-item (batch) to get the raw Notion SDK response.
BEFORE YOU INSTALL
2 tools when we connected. notion_execute and notion_describe front 43 operations such as create_page and query_database. NOTION_ALLOWED_OPERATIONS, NOTION_BLOCKED_OPERATIONS and NOTION_READ_ONLY can disable operations.
CONTEXT COST
Rated by the size of the 2 tool definitions that ride along on every turn, not by how many there are
INSTALLATION
npx -y notion-mcp-serverclaude mcp add notion -s user \
-e NOTION_TOKEN=<YOUR_NOTION_TOKEN> \
-- npx -y notion-mcp-server{
"mcpServers": {
"notion": {
"command": "npx",
"args": [
"-y",
"notion-mcp-server"
],
"env": {
"NOTION_TOKEN": "<YOUR_NOTION_TOKEN>"
}
}
}
}claude mcp add notion -s user \
-e NOTION_TOKEN=<YOUR_NOTION_TOKEN> \
-- docker run --rm -i -e NOTION_TOKEN ghcr.io/awkoy/notion-mcp-server:latestMCP servers
Shameerpc5029
suekou
orbit-logistics
seonglae