Summary
Connects to Notion's internal web API using browser credentials (token_v2, user ID, space ID) instead of the official integration flow. Exposes full-text search across your workspace, bidirectional markdown conversion (export pages to markdown with clean formatting, import or append markdown back into pages), page creation, image uploads, and comment management. Skips the OAuth dance and admin approval process by using the same endpoints the web app calls. Trade-off is token expiry and reliance on an undocumented API. Useful when you want programmatic Notion access without workspace admin permissions or need markdown-based workflows that the official blocks API doesn't support. Includes a one-command setup that extracts credentials from a cURL command copied from DevTools.
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →
Tools
Public tool metadata for what this MCP can expose to an agent.
14 tools
notion-searchPerform a search over: - "internal": Semantic search over Notion workspace and connected sources (Slack, Google Drive, Github, Jira, Microsoft Teams, Sharepoint, OneDrive, Linear). Supports filtering by creation date and creator. - "user": Search for users by name or email. Au...9 params
Perform a search over: - "internal": Semantic search over Notion workspace and connected sources (Slack, Google Drive, Github, Jira, Microsoft Teams, Sharepoint, OneDrive, Linear). Supports filtering by creation date and creator. - "user": Search for users by name or email. Au...
Parameters* required
querystringSemantic search query over your entire Notion workspace and connected sources (Slack, Google Drive, Github, Jira, Microsoft Teams, Sharepoint, OneDrive, or Linear). For best results, don't provide more than one question per tool call. Use a separate "search" tool call for each search you want to perform.
Alternatively, the query can be a substring or keyword to find users by matching against their name or email address. For example: "john" or "john@example.com"
filtersobjectOptionally provide filters to apply to the search results. Only valid when query_type is 'internal'.
page_urlstringOptionally, provide the URL or ID of a page to search within. This will perform a semantic search over the content within and under the specified page. Accepts either a full page URL (e.g. https://notion.so/workspace/Page-Title-1234567890) or just the page ID (UUIDv4) with or without dashes.
page_sizeintegerMaximum number of results to return (default 10). Lower values reduce response size.
query_typestringone of
internal · userteamspace_idstringOptionally, provide the ID of a teamspace to restrict search results to. This will perform a search over content within the specified teamspace only. Accepts the teamspace ID (UUIDv4) with or without dashes.
data_source_urlstringOptionally, provide the URL of a Data source to search. This will perform a semantic search over the pages in the Data Source. Note: must be a Data Source, not a Database. <data-source> tags are part of the Notion flavored Markdown format returned by tools like fetch. The full spec is available in the create-pages tool description.
content_search_modestringone of
workspace_search · ai_searchmax_highlight_lengthintegerMaximum character length for result highlights (default 200). Set to 0 to omit highlights entirely.
notion-fetchRetrieves details about a Notion entity (page, database, or data source) by URL or ID. Provide URL or ID in `id` parameter. Make multiple calls to fetch multiple entities. Pages use enhanced Markdown format. For the complete specification, fetch the MCP resource at `notion://d...3 params
Retrieves details about a Notion entity (page, database, or data source) by URL or ID. Provide URL or ID in `id` parameter. Make multiple calls to fetch multiple entities. Pages use enhanced Markdown format. For the complete specification, fetch the MCP resource at `notion://d...
Parameters* required
idstringThe ID or URL of the Notion page, database, or data source to fetch. Supports notion.so URLs, Notion Sites URLs (*.notion.site), raw UUIDs, and data source URLs (collection://...).
include_transcriptbooleaninclude_discussionsbooleannotion-create-pages## Overview Creates one or more Notion pages, with the specified properties and content. ## Parent All pages created with a single call to this tool will have the same parent. The parent can be a Notion page ("page_id") or data source ("data_source_id"). If the parent is omitt...2 params
## Overview Creates one or more Notion pages, with the specified properties and content. ## Parent All pages created with a single call to this tool will have the same parent. The parent can be a Notion page ("page_id") or data source ("data_source_id"). If the parent is omitt...
Parameters* required
pagesarrayThe pages to create.
parentvalueThe parent under which the new pages will be created. This can be a page (page_id), a database page (database_id), or a data source/collection under a database (data_source_id). If omitted, the new pages will be created as private pages at the workspace level. Use data_source_id when you have a collection:// URL from the fetch tool.
notion-update-page## Overview Update a Notion page's properties or content. ## Properties Notion page properties are a JSON map of property names to SQLite values. For pages in a database: - ALWAYS use the "fetch" tool first to get the data source schema and the exact property names. - Provide...11 params
## Overview Update a Notion page's properties or content. ## Properties Notion page properties are a JSON map of property names to SQLite values. For pages in a database: - ALWAYS use the "fetch" tool first to get the data source schema and the exact property names. - Provide...
Parameters* required
iconstringAn emoji character (e.g. "🚀"), a custom emoji by name (e.g. ":rocket_ship:"), or an external image URL. Use "none" to remove the icon. Omit to leave unchanged. Can be set alongside any command.
coverstringAn external image URL for the page cover. Use "none" to remove the cover. Omit to leave unchanged. Can be set alongside any command.
commandstringone of
update_properties · update_content · replace_content · apply_template · update_verificationnew_strstringRequired for "replace_content" command. The new content string to replace the entire page content with.
page_idstringThe ID of the page to update, with or without dashes.
propertiesobjectRequired for "update_properties" command. A JSON object that updates the page's properties. For pages in a database, use the SQLite schema definition shown in <database>. For pages outside of a database, the only allowed property is "title", which is the title of the page in inline markdown format. Use null to remove a property's value.
template_idstringRequired for "apply_template" command. The ID of a template to apply to this page. Template content is appended to any existing page content.
content_updatesarrayRequired for "update_content" command. An array of search-and-replace operations, each with old_str (content to find) and new_str (replacement content).
verification_statusstringone of
verified · unverifiedallow_deleting_contentbooleanverification_expiry_daysintegerOptional for "update_verification" command when verification_status is "verified". Number of days until verification expires (e.g. 7, 30, 90). Omit for indefinite verification.
notion-move-pagesMove one or more Notion pages or databases to a new parent.2 params
Move one or more Notion pages or databases to a new parent.
Parameters* required
new_parentvalueThe new parent under which the pages will be moved. This can be a page, the workspace, a database, or a specific data source under a database when there are multiple. Moving pages to the workspace level adds them as private pages and should rarely be used.
page_or_database_idsarrayAn array of up to 100 page or database IDs to move. IDs are v4 UUIDs and can be supplied with or without dashes (e.g. extracted from a <page> or <database> URL given by the "search" or "fetch" tool). Data Sources under Databases can't be moved individually.
notion-duplicate-pageDuplicate a Notion page. The page must be within the current workspace, and you must have permission to access it. The duplication completes asynchronously, so do not rely on the new page identified by the returned ID or URL to be populated immediately. Let the user know that...1 params
Duplicate a Notion page. The page must be within the current workspace, and you must have permission to access it. The duplication completes asynchronously, so do not rely on the new page identified by the returned ID or URL to be populated immediately. Let the user know that...
Parameters* required
page_idstringThe ID of the page to duplicate. This is a v4 UUID, with or without dashes, and can be parsed from a Notion page URL.
notion-create-databaseCreates a new Notion database using SQL DDL syntax. If no title property provided, "Name" is auto-added. Returns Markdown with schema, SQLite definition, and data source ID in <data-source> tag for use with update_data_source and query_data_sources tools. The schema param acce...4 params
Creates a new Notion database using SQL DDL syntax. If no title property provided, "Name" is auto-added. Returns Markdown with schema, SQLite definition, and data source ID in <data-source> tag for use with update_data_source and query_data_sources tools. The schema param acce...
Parameters* required
titlestringThe title of the new database.
parentobjectThe parent under which to create the new database. If omitted, the database will be created as a private page at the workspace level.
schemastringSQL DDL CREATE TABLE statement defining the database schema. Column names must be double-quoted, type options use single quotes.
descriptionstringThe description of the new database.
notion-update-data-sourceUpdate a Notion data source's schema, title, or attributes using SQL DDL statements. Returns Markdown showing updated structure and schema. Accepts a data source ID (collection ID from fetch response's <data-source> tag) or a single-source database ID. Multi-source databases r...6 params
Update a Notion data source's schema, title, or attributes using SQL DDL statements. Returns Markdown showing updated structure and schema. Accepts a data source ID (collection ID from fetch response's <data-source> tag) or a single-source database ID. Multi-source databases r...
Parameters* required
titlestringThe new title of the data source.
in_trashbooleanis_inlinebooleanstatementsstringSemicolon-separated SQL DDL statements to update the schema. Supports ADD COLUMN, DROP COLUMN, RENAME COLUMN, ALTER COLUMN SET.
descriptionstringThe new description of the data source.
data_source_idstringThe data source to update. Accepts a collection:// URI from <data-source> tags, a bare UUID, or a database ID (only if the database has a single data source).
notion-create-commentAdd a comment to a page or specific content. Creates a new comment. Provide `page_id` to identify the page, then choose ONE targeting mode: - `page_id` alone: Page-level comment on the entire page - `page_id` + `selection_with_ellipsis`: Comment on specific block content - `di...4 params
Add a comment to a page or specific content. Creates a new comment. Provide `page_id` to identify the page, then choose ONE targeting mode: - `page_id` alone: Page-level comment on the entire page - `page_id` + `selection_with_ellipsis`: Comment on specific block content - `di...
Parameters* required
page_idstringThe ID of the page to comment on (with or without dashes).
rich_textarrayAn array of rich text objects that represent the content of the comment.
discussion_idstringThe ID or URL of an existing discussion to reply to (e.g., discussion://pageId/blockId/discussionId).
selection_with_ellipsisstringUnique start and end snippet of the content to comment on. DO NOT provide the entire string. Instead, provide up to the first ~10 characters, an ellipsis, and then up to the last ~10 characters. Make sure you provide enough of the start and end snippet to uniquely identify the content. For example: "# Section heading...last paragraph."
notion-get-commentsGet comments and discussions from a Notion page. Returns discussions with full comment content in XML format. By default, returns page-level discussions only. Tip: Use the `fetch` tool with `include_discussions: true` first to see where discussions are anchored in the page con...4 params
Get comments and discussions from a Notion page. Returns discussions with full comment content in XML format. By default, returns page-level discussions only. Tip: Use the `fetch` tool with `include_discussions: true` first to see where discussions are anchored in the page con...
Parameters* required
page_idstringIdentifier for a Notion page.
discussion_idstringFetch a specific discussion by ID or discussion URL (e.g., discussion://pageId/blockId/discussionId).
include_resolvedbooleaninclude_all_blocksbooleannotion-get-teamsRetrieves a list of teams (teamspaces) in the current workspace. Shows which teams exist, user membership status, IDs, names, and roles. Teams are returned split by membership status and limited to a maximum of 10 results. <examples> 1. List all teams (up to the limit of each...1 params
Retrieves a list of teams (teamspaces) in the current workspace. Shows which teams exist, user membership status, IDs, names, and roles. Teams are returned split by membership status and limited to a maximum of 10 results. <examples> 1. List all teams (up to the limit of each...
Parameters* required
querystringOptional search query to filter teams by name (case-insensitive).
notion-get-usersRetrieves a list of users in the current workspace. Shows workspace members and guests with their IDs, names, emails (if available), and types (person or bot). Supports cursor-based pagination to iterate through all users in the workspace. <examples> 1. List all users (first p...4 params
Retrieves a list of users in the current workspace. Shows workspace members and guests with their IDs, names, emails (if available), and types (person or bot). Supports cursor-based pagination to iterate through all users in the workspace. <examples> 1. List all users (first p...
Parameters* required
querystringOptional search query to filter users by name or email (case-insensitive).
user_idstringReturn only the user matching this ID. Pass "self" to fetch the current user.
page_sizeintegerNumber of users to return per page (default: 100, max: 100).
start_cursorstringCursor for pagination. Use the next_cursor value from the previous response to get the next page.
notion-create-viewCreate a new view on a Notion database. Exactly one of "database_id" or "parent_page_id" must be provided: - "database_id": add a new view tab to an existing database. - "parent_page_id": create an inline linked database view on a page that references the existing "data_source...6 params
Create a new view on a Notion database. Exactly one of "database_id" or "parent_page_id" must be provided: - "database_id": add a new view tab to an existing database. - "parent_page_id": create an inline linked database view on a page that references the existing "data_source...
Parameters* required
namestringThe name of the view.
typestringone of
table · board · list · calendar · timeline · galleryconfigurestringView configuration DSL string. Supports FILTER, SORT BY, GROUP BY, CALENDAR BY, TIMELINE BY, MAP BY, CHART, FORM, SHOW, HIDE, COVER, WRAP CELLS, and FREEZE COLUMNS directives. See notion://docs/view-dsl-spec.
database_idstringThe database to add a view tab to. Accepts a Notion URL or a bare UUID. Mutually exclusive with `parent_page_id`; exactly one must be provided.
data_source_idstringThe data source (collection) ID. Accepts a collection:// URI from <data-source> tags or a bare UUID.
parent_page_idstringA page to create an inline linked database view on. Accepts a Notion URL or a bare UUID. The new linked view block is appended at the end of the page and references `data_source_id`. Mutually exclusive with `database_id`; exactly one must be provided.
notion-update-viewUpdate a view's name, filters, sorts, or display configuration. Use "fetch" to get view IDs from database responses. Only include fields you want to change. The "configure" param uses the same DSL as create_view. Use CLEAR to remove settings: - CLEAR FILTER — remove all filter...3 params
Update a view's name, filters, sorts, or display configuration. Use "fetch" to get view IDs from database responses. Only include fields you want to change. The "configure" param uses the same DSL as create_view. Use CLEAR to remove settings: - CLEAR FILTER — remove all filter...
Parameters* required
namestringNew name for the view.
view_idstringThe view to update. Accepts a view:// URI, a Notion URL with ?v= parameter, or a bare UUID.
configurestringView configuration DSL string. Supports FILTER, SORT BY, GROUP BY, CALENDAR BY, TIMELINE BY, MAP BY, CHART, FORM, SHOW, HIDE, COVER, WRAP CELLS, FREEZE COLUMNS, and CLEAR directives.
@shck-dev/notion-mcp
Notion MCP Server — search, export, and import pages as markdown
No workspace admin. No OAuth. No page sharing.
Just paste 3 values from your browser and go.
Features
- Search — full-text search across your entire workspace
- Export — download any page as clean markdown (headings, lists, to-do, code blocks, tables, links, images with viewable URLs)
- Import — write markdown back to Notion pages (replaces content), from a string or local file
- Append — add markdown to the end of a page without touching existing content
- Create — spin up new child pages, optionally prefilled from a markdown string or file
- Images — upload a local image to a page, or reference an external URL
- Comments — list open discussions, add new comments, reply to threads
- One-command setup —
npx @shck-dev/notion-mcp init: paste a browser "Copy as cURL" and it extracts + saves your credentials - Prompts & resources — a
notion_setupprompt and anotion://guideresource for in-client onboarding - Zero setup friction — uses the same internal API as the Notion web app; if you can see it in your browser, this server can access it
Tools
| Tool | Description |
|---|---|
notion_search | Full-text search across all pages in your workspace |
notion_export_page | Export any Notion page as markdown; image links resolve to viewable CDN URLs (pass image_dir to download images locally instead) |
notion_import_page | Write markdown to a Notion page — replaces all existing content |
notion_import_page_from_file | Write a local .md file to a page — replaces all content |
notion_append_to_page | Append markdown to the end of a page (non-destructive) |
notion_append_to_page_from_file | Append a local .md file to the end of a page (non-destructive) |
notion_create_page | Create a new sub-page, optionally prefilled with markdown |
notion_create_page_from_file | Create a new sub-page from a local .md file |
notion_add_image | Append an image to the end of a page — local file is uploaded to Notion, http(s) URL is referenced as-is |
notion_list_comments | List open discussion threads on a page |
notion_add_comment | Start a new discussion — inline (anchored to text) or block-level |
notion_reply_comment | Reply to an existing discussion thread |
notion_init | Paste a browser "Copy as cURL" to extract & save credentials |
Why not the official Notion API?
| This MCP server | Official Notion API | |
|---|---|---|
| Setup | Paste 3 values from DevTools | Create integration, get admin approval, share pages |
| Page access | Everything you can see | Only explicitly shared pages |
| Markdown | Bidirectional (export + import) | Read-only blocks API |
| Auth | Cookie (token_v2) | OAuth / integration token |
Trade-off: The internal API is undocumented and may change. Token expires periodically (re-grab from browser).
Quick start
Easiest: interactive setup
npx @shck-dev/notion-mcp init
Open Notion in Chrome → DevTools (F12) → Network → click any request to notion.so/api/v3/… → right-click → Copy as cURL, then paste it and press Ctrl-D. Your token, user id, and workspace id are extracted and saved to ~/.notion-mcp/config.json. Then register the server — no env block needed:
claude mcp add notion -- npx @shck-dev/notion-mcp
Prefer to set the three values by hand? Steps below.
1. Get credentials from your browser
- Open notion.so in Chrome
- Press F12 → Application → Cookies →
www.notion.so - Copy the
token_v2cookie value →NOTION_TOKEN - Press F12 → Network tab, do any action in Notion
- Find a POST request to
api/v3/*, click it - From Request Headers: copy
x-notion-active-user-header→NOTION_USER_ID - From Request Body (Payload): find
spaceId→NOTION_SPACE_ID
2. Configure your MCP client
Claude Code
claude mcp add notion -- env NOTION_TOKEN=your_token NOTION_USER_ID=your_user_id NOTION_SPACE_ID=your_space_id npx @shck-dev/notion-mcp
Claude Desktop / Cursor / any MCP client
Add to your MCP config (claude_desktop_config.json, .cursor/mcp.json, etc.):
{
"mcpServers": {
"notion": {
"command": "npx",
"args": ["@shck-dev/notion-mcp"],
"env": {
"NOTION_TOKEN": "your_token_v2_value",
"NOTION_USER_ID": "your_user_id",
"NOTION_SPACE_ID": "your_space_id"
}
}
}
}
Requirements
- Node.js ≥ 18 (for
npx) — or Bun. The published server is compiled to node-compatible JS, so Bun is no longer required to run it.
Limitations
- Internal API — undocumented, may break with Notion updates
- Token expiry —
token_v2expires periodically; re-grab from browser when auth fails - Databases — database/collection pages don't export rows yet; sub-pages render as links and such pages return an explanatory note instead of empty output
- Block granularity — import replaces all content, append adds to the end (no in-place editing of individual blocks)
- Lossy markdown — some complex formatting may simplify during conversion (e.g. nested lists flatten on import)
- External images — http(s) image URLs added via
notion_add_image(or embedded in markdown) are referenced as-is and not re-uploaded to Notion
License
MIT
Featured
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →Configuration
NOTION_TOKEN*secretNotion token_v2 cookie value from browser DevTools
NOTION_USER_ID*Notion user ID from x-notion-active-user-header
NOTION_SPACE_ID*Notion workspace ID from API request body
Registryactive
Package@shck-dev/notion-mcp
TransportSTDIO
AuthRequired
UpdatedMay 31, 2026
