NotionSAFE
A Model Context Protocol server for connecting Notion to MCP-compatible clients
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
AI-friendly MCP server for the Notion API. It helps agents find, read, query, and update Notion workspaces while keeping responses compact enough for day-to-day AI workflows.
This server targets the Notion API 2026-03-11 and uses the current database/data source model. It exposes MCP tools, prompts, resources, structured tool results, and optional MCP Apps for interactive Notion workflows.
Highlights
- Search and target discovery with
notion_find. - Compact page reading with stable block IDs via
notion_read_page. - Data source schema inspection with
notion_inspect_data_source. - Schema-aware data source querying and item creation with simple values.
- Simple page editing tools for paragraphs, headings, lists, todos, quotes, callouts, code blocks, dividers, and safe Markdown append.
- Raw Notion API tools for advanced block, page, database, data source, comment, and user operations.
- Optional MCP Apps: Data Source Explorer and Page Workbench.
Quick Start
Add this server to an MCP host such as Claude Desktop:
{
"mcpServers": {
"notion": {
"command": "npx",
"args": ["-y", "@suekou/mcp-notion-server"],
"env": {
"NOTION_API_TOKEN": "your-integration-token"
}
}
}
}Restart your MCP host after saving the configuration.
Setup Guide
1. Create a Notion integration
Open the Notion integrations dashboard, then create a new internal integration.
2. Configure capabilities
Grant only the capabilities you need:
- Read content: required for search, page reads, data source retrieval, and queries.
- Insert content: required for creating pages/items and appending blocks.
- Update content: required for updating pages, blocks, and data source schemas.
- Read comments / Insert comments: required only for c
be526f46a4d1OBSERVED · 2026-09-26Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control. Replace the environment placeholders with a token scoped to the least it needs.
claude mcp add mcp-notion-server --env NOTION_API_TOKEN=${NOTION_API_TOKEN} -- npx -y @suekou/[email protected]{
"mcpServers": {
"mcp-notion-server": {
"command": "npx",
"args": [
"-y",
"@suekou/[email protected]"
],
"env": {
"NOTION_API_TOKEN": "${NOTION_API_TOKEN}"
}
}
}
}Exposed tools (34)
22 read · 11 write · 1 destructive. Blast radius: 1 tool can delete or overwrite — an agent that can be talked into calling a tool can be talked into calling this one.
| Tool | Risk | Description |
|---|---|---|
content | read | The content to append. |
data_source | read | The data source name or ID. |
item | write | The item to create, described in natural language. |
notion_append_block_children | read | Append new children blocks to a specified parent block in Notion. Requires insert content capabilities. Use the optional |
notion_append_page_content | write | Append or update readable Notion page content using simplified content tools. |
notion_create_comment | write | Create a comment in Notion. This requires the integration to have |
notion_create_data_source | write | Add an additional Notion data source to an existing database. Do not use this to create a new database; use notion_create_database for that. |
notion_create_data_source_item | write | Create a new page item in a Notion data source. Use the data_source_id, not the database_id, as the parent. |
notion_create_data_source_item_workflow | write | Create a data source item using schema inspection and simple property values. |
notion_create_database | write | Create a Notion database and its initial data source. Use this when the user wants a new database. For Notion API 2025-09-03+, put the initial schema under initial_data_source.properties. |
notion_delete_block | destructive | Delete a block in Notion |
notion_find_target | read | Find the right Notion page or data source before reading, editing, or creating content. |
notion_inspect_data_source | read | Inspect a Notion data source schema and return a compact property summary for AI agents. Use this before creating or updating items so the model can choose valid property names, option values, and relation targets without reading the full Notion API object. |
notion_list_all_users | read | List all users in the Notion workspace. **Note:** This function requires upgrading to the Notion Enterprise plan and using an Organization API key to avoid permission errors. |
notion_open_data_source_app | read | Open an interactive Notion Data Source Explorer MCP App for schema inspection, filter building, querying, and item creation from simple values. |
notion_open_page_workbench | read | Open an interactive Notion Page Workbench MCP App for reading page content, selecting block IDs, updating simple blocks, and appending Markdown. |
notion_query_data_source | read | Query a Notion data source with filters, sorts, and pagination. Use notion_retrieve_database first when you only have a database ID and need to discover its data_source_id. |
notion_query_data_source_items_workflow | read | Query data source items using schema inspection and simple filters. |
notion_retrieve_block | read | Retrieve a block from Notion |
notion_retrieve_block_children | read | Retrieve the children of a block |
notion_retrieve_bot_user | read | Retrieve the bot user associated with the current token in Notion |
notion_retrieve_comments | read | Retrieve a list of unresolved comments from a Notion page or block. Requires the integration to have |
notion_retrieve_data_source | read | Retrieve metadata and property schema for a Notion data source. |
notion_retrieve_database | read | Retrieve a Notion database container and its child data_sources. Use this to discover which data_source_id should be used for query, schema, and item creation operations. |
notion_retrieve_page | read | Retrieve a page from Notion |
notion_retrieve_user | read | Retrieve a specific user by user_id in Notion. **Note:** This function requires upgrading to the Notion Enterprise plan and using an Organization API key to avoid permission errors. |
notion_search | read | Search pages or data sources by title in Notion |
notion_update_block | write | Update the content of a block in Notion based on its type. The update replaces the entire value for a given field. |
notion_update_content | write | Update an existing Notion block without writing raw Notion block JSON. Use this after notion_read_page gives you a block ID and you need to replace the text or simple fields of an existing paragraph, heading, list item, todo, quote, callout, or code block. The item.type must match the block |
notion_update_data_source | write | Update a Notion data source title, description, or properties. |
notion_update_page_properties | write | Update properties of a page or an item in a Notion database |
page | read | The page title or ID. |
query | read | The items to find, described in natural language. |
target | read | The title, partial name, or description of the Notion target. |
Trust audit
SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | PASS |
| L1 | Static analysis of the code | PASS |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | WARN |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- declared (6 observation(s))
- Network
- declared (1 observation(s))
- Shell
- none-observed
- Dependencies
- not all pinned
- Secrets in source
- none-found
Findings (8)
notion_delete_block
.node-version
new URL(`../../build/apps/assets/${assetName}`, import.meta.url),import { commonIdDescription, formatParameter } from "../../mcp/schema.js";} from "../../mcp/schema.js";
import type { BlockResponse } from "../../notion/types.js";import { commonIdDescription, formatParameter } from "../../mcp/schema.js";yargs, zod, @types/node, @types/yargs, typescript
Gates applied: no_behavioural_pass.
be526f46a4d1full audit observations/trust-audit/mcp-server/suekou__notion-11.json · Report an issue / request a re-scanAudit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-09-26 | be526f46a4d1 | SAFE | B | 89 | first audit |
Questions
What is the Notion MCP server?
A Model Context Protocol server for connecting Notion to MCP-compatible clients
What tools does Notion expose?
34 in total: 22 read-only, 11 that write, and 1 that can delete or overwrite (notion_delete_block). Every one is listed on this page with its risk.
Is Notion safe to connect to an agent?
The audit found nothing in the source that contradicts what it says it does, and graded it B (89/100). Grade A is held back for packages that have also passed a sandboxed behavioural run, which is why a clean server reads B. Separately from the audit: 1 of its tools can destroy data, so scope the token you give it to what you actually need.
What credentials does Notion need?
It reads NOTION_API_TOKEN from the environment. Give it a token scoped to the least it needs — an agent that can be talked into calling a tool can be talked into calling it with your credentials.
How does Notion run?
It speaks stdio, so it runs as a local process your client starts. It is published on npm as @suekou/mcp-notion-server at 2.0.2.
How current is this page?
The grade is for one exact copy of the source (be526f46a4d1), read on 2026-09-26. The repository is watched and re-audited when it changes.