Which integrations are available for this server?

Provides full read/write access to any Notion page visible to your account, allowing search, create, edit, and delete operations on pages and blocks using Notion's private API.

notion-private-api-mcp

by kirvigen

Overview Schema Source Related Servers Discussions Admin

JavaScript

Remote

Notion Private API MCP Server

License: MIT Node.js MCP PRs Welcome

An unofficial Notion MCP server built on Notion's private API (token_v2). It gives Claude Desktop, Claude Code, Cursor and any other MCP client full read/write access to your entire Notion workspace — with no integration token and without sharing pages one by one.

Unlike servers built on the official Notion API, this one authenticates with your browser session cookie, so an LLM agent can search, read, create and edit any page your account can see — instantly, with zero setup in Notion. Built on the official @modelcontextprotocol/sdk (stdio transport).

Why this server?

	This server (private API)	Official Notion API / MCP
Setup in Notion	None — just your browser cookie	Create an integration + share each page
Access scope	Everything your account can see	Only pages explicitly shared with the integration
Auth	`token_v2` session cookie	Integration token / OAuth
Best for	Personal automation, full-workspace agents	Production apps, multi-user, official support
Stability	⚠️ Fragile, undocumented	✅ Stable, supported

If you just want an agent over your own workspace without fighting integration permissions, this is the fastest path. For production / multi-tenant apps, use the official Notion MCP server.

Related MCP server: notion-full-mcp

⚠️ Important: this uses Notion's private API

This server talks to Notion's undocumented internal API (https://www.notion.so/api/v3), not the official public API:

Auth is your browser cookie (token_v2) — effectively your account password. Never commit it.
Notion can change or break this API at any time, and using it may be against Notion's ToS.
It is inherently fragile and not for production — use at your own risk, with your own data.

Quick start

git clone https://github.com/kirvigen/notion-private-api-mcp.git
cd notion-private-api-mcp
npm install
export NOTION_TOKEN_V2='your_token_v2'   # see "Configuration" below
npm start

Then register it in your MCP client (Claude Desktop / Claude Code).

Tools

Tool	Description
`get_page`	Read a page block and its metadata
`get_block`	Read a single block
`get_block_children`	Read the direct child blocks of a page or block
`get_style_documentation`	Catalog of supported block types & inline annotations (call before composing complex pages)
`markdown_to_blocks`	Preview how Markdown parses into the simplified block JSON
`create_page`	Create a child page under another page, from blocks or Markdown
`append_blocks`	Append blocks/Markdown to a page (at the end, or after a given block)
`replace_page_content`	Replace the direct child blocks of a page
`update_block_text`	Replace the plain-text content of a block (e.g. a code block)
`delete_blocks`	Remove (archive) direct child blocks from a page
`sync_markdown_file`	Create or replace a page from a local Markdown file

Tool parameters are defined in src/server.js.

Configuration

Configured entirely through environment variables:

Variable	Required	Description
`NOTION_TOKEN_V2`	✅	Your Notion session cookie (`token_v2`)
`NOTION_PRIVATE_API_BASE`	—	API base URL (default: `https://www.notion.so`)

Getting your `token_v2`

Log in to Notion in your browser: https://www.notion.so
Open DevTools (F12) → Application → Cookies → https://www.notion.so
Copy the value of the token_v2 cookie.

🔒 Treat it like a password. Keep it in your shell env or an untracked .env — never commit it.

cp .env.example .env   # then edit .env

Usage with MCP clients

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "notion-private": {
      "command": "node",
      "args": ["/absolute/path/to/notion-private-api-mcp/src/server.js"],
      "env": { "NOTION_TOKEN_V2": "your_token_v2" }
    }
  }
}

Claude Code

claude mcp add notion-private \
  --scope local \
  --env NOTION_TOKEN_V2='your_token_v2' \
  -- node /absolute/path/to/notion-private-api-mcp/src/server.js

The helper scripts ./run-desktop.sh and ./run-codex.sh resolve the repo path automatically and log to /tmp.

Example prompts

Once connected, just talk to your agent:

"Find my 'Q3 Roadmap' page in Notion and summarize it."
"Create a child page under titled 'Meeting notes' with today's action items."
"Append a TODO list to with these three tasks…"
"Sync my local CHANGELOG.md into the release-notes page."

Writing content

Tools that write accept a plain-JSON simplified block format:

[
  { "type": "heading_1", "text": "Release Notes" },
  { "type": "paragraph", "text": "First paragraph." },
  { "type": "to_do", "text": "Ship the feature", "checked": true },
  { "type": "toggle", "text": "Details", "children": [
    { "type": "bulleted_list_item", "text": "Item one" }
  ]}
]

Supported types: paragraph, heading_1/2/3, bulleted_list_item, numbered_list_item, to_do, toggle, quote, callout, code, divider.

You can also pass Markdown (a stable subset: headings, paragraphs, bullet/numbered lists, task items, blockquotes, fenced code, horizontal rules). Call get_style_documentation from your client for the authoritative, machine-readable catalog. Nested lists, tables and inline formatting are not implemented yet.

Troubleshooting / FAQ

Where do I get token_v2? See Getting your token_v2.

NOTION_TOKEN_V2 is required — the env var isn't set in the process that launches the server (check your MCP client's env block, not just your shell).

My token stopped working — token_v2 expires when your Notion session ends (logout, password change, long inactivity). Grab a fresh cookie and update it.

MemcachedCrossCellError — a transient Notion routing error on multi-cell workspaces. The client already retries and falls back to loadPageChunk; just retry the call if it surfaces.

Is this against Notion's ToS? It uses an undocumented internal API. Use only with your own account and data, at your own risk.

Project layout

src/
├── server.js         # MCP server: tool registration + stdio transport
├── notion-client.js  # Private-API client (cookie auth, transactions, retries)
├── notion-blocks.js  # Builds Notion block trees from simplified blocks
├── markdown.js       # Markdown → simplified-block parser
└── style-docs.js     # Catalog returned by get_style_documentation

Contributing

Issues and PRs are welcome. If this saved you time, please ⭐ the repo — it genuinely helps others discover it.

License

MIT © kir.vigen

Disclaimer

Not affiliated with Notion Labs, Inc. Relies on an undocumented internal API; by using it you accept all risks, including possible account restrictions and breakage when the API changes. Use only with your own data.

Available Tools

11 tools

append_blocksAppend BlocksB

Append simplified blocks or Markdown to a page. Inserts at the end by default; pass after_block_id to insert immediately after a specific direct child block.

ParametersJSON Schema

Name	Required	Description
`page_id`	Yes	Page id or page URL.
`markdown`	No	Markdown content to convert into blocks.
`blocks`	No	Simplified block JSON.
`after_block_id`	No	Optional id of an existing direct child block; new blocks are inserted immediately after it. Must be a direct child of page_id.

TDQS

B3.4/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description must disclose all behavioral traits. Only mentions insertion position (end or after block). Missing details like idempotency, error conditions, limits, or what 'simplified blocks' entails.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences front-load core action and optional behavior. No redundant or extraneous text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Describes main insertion behavior but lacks explanation of 'simplified blocks', markdown conversion, or return values (no output schema). Missing details that could help agent understand tool's scope vs siblings like markdown_to_blocks.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers all parameters with descriptions. Description adds context: after_block_id inserts after a specific direct child. This clarifies usage beyond schema, compensating for 100% schema coverage (baseline 3).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Verb 'append' clearly states action; 'blocks or Markdown to a page' identifies resource. Not explicitly contrasted with siblings like replace_page_content or update_block_text, but use of 'append' and optional after_block_id provides differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Describes default behavior (insert at end) and optional parameter usage. No guidance on when to use this tool versus other block manipulation tools, nor prerequisites or restrictions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_pageCreate Notion PageB

Create a child page under another page from blocks or Markdown.

ParametersJSON Schema

Name	Required	Description
`parent_page_id`	Yes	Parent page id or page URL.
`title`	Yes	Title for the new page.
`markdown`	No	Markdown content to convert into blocks.
`blocks`	No	Simplified block JSON.

TDQS

B3.4/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It only states 'create', which implies mutation, but does not disclose permissions, idempotency, side effects, or output behavior. This is insufficient for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence of 14 words with no waste. Every word contributes to understanding the tool's purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations, no output schema, and 4 parameters, the description is minimal. It lacks explanation of return values, error cases, prerequisites, or how markdown vs blocks interact. The agent may be left guessing critical details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with clear descriptions for all parameters. The tool description adds 'from blocks or Markdown', which groups the two optional parameters, but does not add significant new meaning beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool creates a child page under another page using blocks or Markdown. It uses a specific verb (create) and resource (child page), and distinguishes from siblings like append_blocks and get_page.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use (when creating a new page as child), but does not provide explicit guidance on when not to use or alternatives. For example, it doesn't mention markdown_to_blocks as a precursor if only conversion is needed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete_blocksDelete BlocksA

Remove direct child blocks from a page and archive those blocks.

ParametersJSON Schema

Name	Required	Description	Default
`page_id`	Yes	Parent page id or page URL.
`block_ids`	Yes	Block ids or block URLs to remove from the page.

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must carry the full burden. It discloses that blocks are archived, adding some behavioral context, but does not mention permissions, irreversibility, or side effects on the page.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single concise sentence that directly states the tool's action and result. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with two well-described parameters and no output schema, the description covers the core functionality adequately. It could mention error conditions or return values, but it is complete enough for the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds that blocks are 'direct child blocks', providing context beyond the schema's description of block IDs. This extra detail enhances parameter understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool removes direct child blocks from a page and archives them, using specific verbs and resource. It distinguishes from sibling tools like append_blocks and update_block_text which perform different operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidelines are provided for when to use this tool versus alternatives. There is no mention of prerequisites, scenarios, or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_blockGet Notion BlockB

Read a single Notion block through the private API.

ParametersJSON Schema

Name	Required	Description	Default
`block_id`	Yes	Block id or block URL.

TDQS

B3.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden of behavioral disclosure. It states 'Read' indicating a non-destructive operation, but does not mention authentication requirements, rate limits, or that it uses a 'private API' which might imply instability. The description is minimally adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence, front-loaded with the core action. Every word serves a purpose with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite the tool's simplicity (1 parameter, no output schema), the description fails to explain what the return value is or how the output is structured. Given the sibling tools, more context on distinguishing use cases would be helpful.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the description adds no additional meaning beyond the schema's 'Block id or block URL.' Since the schema already documents the parameter, the description provides no extra value, meeting the baseline for high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Read a single Notion block' providing a specific verb and resource. It implies it is for individual blocks, distinguishing from siblings like 'get_block_children' which reads children. However, it does not explicitly differentiate from 'get_page' which might read a page entity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like 'get_block_children' or 'get_page'. It lacks any contextual cues such as prerequisites or scenarios where this tool is preferred.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_block_childrenGet Notion Block ChildrenB

Read direct child blocks for a page or block through the private API.

ParametersJSON Schema

Name	Required	Description	Default
`block_id`	Yes	Parent block id or page id.

TDQS

B3.2/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It only mentions 'through the private API', hinting at access restrictions but not detailing auth, rate limits, or error handling. This is insufficient for full transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is concise and front-loaded with the core action. While effective, it could be slightly more structured with separating the purpose from the API context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one parameter and no output schema, the description provides minimal but adequate context. However, it lacks details on return format, pagination, or error cases, leaving room for improvement.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% coverage, describing the block_id parameter as 'Parent block id or page id.' The description adds no extra meaning beyond the schema, achieving the baseline score for high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Read' and the resource 'direct child blocks for a page or block', specifying the scope (direct children) and distinguishing it from siblings like get_block (single block) and get_page (page details).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not provide any guidance on when to use this tool versus alternatives like get_block or get_page. There is no mention of prerequisites, exclusions, or context for optimal use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_pageGet Notion PageC

Read a Notion page through the Notion private API.

ParametersJSON Schema

Name	Required	Description	Default
`page_id`	Yes	Notion page id or page URL.

TDQS

C2.8/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It only mentions 'through the Notion private API' without covering behaviors like error handling, read-only nature, or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no wasted words, but it is too brief to provide sufficient information. It balances conciseness and completeness poorly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having only one parameter and no output schema, the description fails to explain what data is returned or how to handle errors. It lacks context for effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a clear description for 'page_id'. The description adds no additional meaning beyond the schema, so a baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Read a Notion page', specifying the verb and resource. It distinguishes from siblings like 'get_block' and 'get_block_children' by the resource type, though it doesn't explicitly contrast them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like 'get_block_children' or 'append_blocks'. Prerequisites or limitations (e.g., page accessibility) are not mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_style_documentationNotion Style DocumentationA

Return the catalog of supported block types, inline annotations (bold/italic/code/link/color/mention), Markdown-to-Notion mapping and block format hints used by this MCP server. Call this before composing complex pages to know what styles you can produce.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A4.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations. Description implies read-only but does not explicitly state absence of side effects, auth needs, or rate limits. Adequate but could be improved.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with contents, then usage. No redundant words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with no output schema, description sufficiently covers return types and use case. Hints at structure enough for an agent to know what to expect.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters; schema coverage is 100%. Baseline of 4 for zero parameters is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Explicitly states it returns a catalog of block types, inline annotations, Markdown mapping, and format hints. Differentiates from sibling tools which manipulate content.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Advises calling before composing complex pages to learn available styles. Clear context but no explicit exclusion or alternative mention; however, siblings are distinct.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

markdown_to_blocksMarkdown To BlocksB

Convert Markdown into the simplified block JSON format.

ParametersJSON Schema

Name	Required	Description	Default
`markdown`	Yes	Markdown source.

TDQS

B3.3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden but only states 'convert'. It does not disclose whether the conversion is pure, if it validates markdown, or what happens on invalid input. No side effects or performance characteristics are mentioned.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is a single, concise sentence with no filler. It is front-loaded with the essential purpose. For a simple conversion tool with one parameter, this level of conciseness is appropriate.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the low complexity (1 required param, no output schema, no nested objects), the description is minimally adequate. However, it lacks information about the output structure, error handling, and any constraints on the markdown input, which would be helpful for an agent to use the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for the single parameter 'markdown', with a basic description 'Markdown source.' The tool description adds the output format ('simplified block JSON'), which indirectly clarifies the input expectations but does not add extra detail like allowed markdown syntax.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool converts markdown to a simplified block JSON format. The verb 'convert' and the resource 'Markdown' are specific, and the tool is distinct from sibling tools like append_blocks and create_page which deal with existing blocks or pages.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. The description does not mention prerequisites, limitations, or when a different tool might be more appropriate, such as if the user already has blocks and needs to append them.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

replace_page_contentReplace Page ContentB

Replace direct child blocks of a page with blocks or Markdown.

ParametersJSON Schema

Name	Required	Description
`page_id`	Yes	Page id or page URL.
`markdown`	No	Markdown content to convert into blocks.
`blocks`	No	Simplified block JSON.

TDQS

B3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It only states the action but does not mention that this operation is destructive (replaces all direct children), whether it is reversible, any authentication requirements, or what happens to existing content. This is insufficient for safe invocation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence and very concise. However, it omits critical details, so conciseness comes at the cost of informativeness. It is front-loaded but not optimally structured for clarity given the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of output schema, annotations, and the presence of 10 sibling tools, the description is too sparse. It fails to explain the replacement behavior (e.g., whether blocks are deleted before adding), error scenarios, or return value. It does not help an agent distinguish between this and similar tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with each parameter having a description (page_id, markdown, blocks). The tool description adds 'Simplified block JSON' for blocks, which aligns with schema. However, it does not provide additional semantics such as format constraints, optionality relationships, or the effect of providing both markdown and blocks.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Replace' and the resource 'direct child blocks of a page', and specifies the inputs as 'blocks or Markdown.' It distinguishes from sibling tools like append_blocks (which appends) and delete_blocks (which deletes) by implying a complete replacement of children.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance is given on when to use this tool over alternatives. The description does not mention prerequisites, when not to use, or contrast with append_blocks or update_block_text. It merely states the action without context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

sync_markdown_fileSync Markdown FileB

Create a new page or replace an existing page from a local Markdown file.

ParametersJSON Schema

Name	Required	Description
`file_path`	Yes	Absolute or relative Markdown file path.
`page_id`	No	Existing page id to replace.
`parent_page_id`	No	Parent page id when creating a new page.
`title`	No	Optional page title override.

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, and description only states 'create or replace' without detailing conditions (e.g., which parameter triggers creation vs replacement), overwrite behavior, idempotency, or required permissions. Minimal disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single concise sentence, front-loaded with key action. Could be improved with structuring (e.g., bullet points), but no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Description lacks behavioral details for a 4-parameter tool with no output schema or annotations. Missing info on parameter interactions, return values, and error scenarios, leaving gaps for agent decision-making.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so description adds little beyond schema. It provides context ('local Markdown file') but does not enhance individual parameter meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'create a new page or replace an existing page from a local Markdown file', specifying verb and resource. It implies a file-based operation, distinguishing it from other page tools like create_page or replace_page_content, but lacks explicit contrast.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description suggests usage when syncing a local Markdown file to a page, but provides no guidance on when to choose this tool over alternatives (e.g., create_page, replace_page_content) or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_block_textUpdate Block TextA

Replace the plain text content of a block (e.g. code block). Inline markdown is NOT parsed — text is stored verbatim.

ParametersJSON Schema

Name	Required	Description	Default
`block_id`	Yes	Block id or block URL.
`text`	Yes	New plain text content for the block.

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses that markdown is not parsed and text is stored verbatim, which is a key behavioral trait. However, it could mention idempotency or side effects like overwriting formatting.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no fluff. First sentence gives action and example, second clarifies the key nuance. Efficient and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter tool with no output schema, the description covers purpose and a critical behavioral constraint. It could mention prerequisites (e.g., block exists) or error scenarios, but overall is fairly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds value by emphasizing 'plain text' and 'verbatim', reinforcing the behavioral constraint beyond the schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Replace the plain text content') and resource ('a block, e.g. code block'), with a specific behavioral note about markdown parsing. It distinguishes itself from siblings like append_blocks or delete_blocks by focusing on updating text content.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides implied context (use when you need verbatim text, not parsed markdown) but does not explicitly state when not to use or suggest alternatives among siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

11 tool updatesv0.1.0May 31, 2026
- First observedappend_blocks
- First observedcreate_page
- First observeddelete_blocks
- First observedget_block
- First observedget_block_children
- First observedget_page
- First observedget_style_documentation
- First observedmarkdown_to_blocks
- First observedreplace_page_content
- First observedsync_markdown_file
- First observedupdate_block_text

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.5/5.0

Scored 2026-05-31 19:50 across 11 tools

Disambiguation5/5

Each tool targets a distinct operation: page vs block CRUD, content replacement, style documentation, and markdown conversion. No meaningful overlap exists between any two tools.

Naming Consistency4/5

Most tools follow a verb_noun pattern (e.g., get_page, delete_blocks). However, markdown_to_blocks deviates by using a descriptor format, breaking the uniform convention.

Tool Count5/5

With 11 tools, the set covers core Notion page and block operations, plus supporting utilities. The count is well-scoped for the private API's capabilities without being excessive.

Completeness3/5

The set covers basic content creation, reading, and modification, but lacks page metadata updates, page deletion, and search. These gaps may hinder some workflows but core content operations are present.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

mcp-serverOAuth
com.niftypm
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Project Management Communication File Systems
2
remnus AOAuth
io.github.Ranork
MCP-native open-source Notion alternative: read & write pages, databases and kanban boards.
Note Taking Project Management Workplace & Productivity
24372
mcpOAuth
com.airtable
Official Airtable MCP server — database and operations layer for agents.
Databases Project Management
2
ClawLinkOAuth
dev.claw-link
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
App Automation Workplace & Productivity
24

Related MCP Servers

Notion MCP Server
Content Management Systems Developer Tools Search
ramidecodes
A
license
C
quality
D
maintenance
A Model Context Protocol (MCP) server that exposes the official Notion SDK, allowing AI models to interact with Notion workspaces.
Updated a year ago (2025-04-01 12:09 UTC)
17
35 npm
10
Apache 2.0
notion-full-mcp
Note Taking Workplace & Productivity
cphoskins
A
license
A
quality
C
maintenance
Full-featured Notion MCP server enabling deep page reading, block editing, snapshot/restore, file uploads, table manipulation, page restore, and destructive page copying.
Updated 5 months ago (2026-04-09 02:22 UTC)
33
MIT
Notion MCP Server
Note Taking Workplace & Productivity
mieubrisse
A
license
Not graded
quality
D
maintenance
A local MCP server for the Notion API, enabling AI agents to read, write, and manage Notion pages and databases. This fork restores database creation support.
Updated 7 months ago (2026-02-21 15:31 UTC)
127 npm
MIT
notion-mcp-hono
Note Taking Search
ldamoredev
F
license
Not graded
quality
B
maintenance
Remote MCP server that exposes Notion as tools (search, get, create pages, append blocks, query databases) via Streamable HTTP with bearer auth, designed for deployment on Railway.
Updated 2 months ago (2026-07-11 22:26 UTC)
-

Notion Private API MCP Server

Why this server?

Table of contents

⚠️ Important: this uses Notion's private API

Quick start

Tools

Configuration

Getting your token_v2

Usage with MCP clients

Claude Desktop

Claude Code

Example prompts

Writing content

Troubleshooting / FAQ

Project layout

Contributing

License

Disclaimer

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Getting your `token_v2`