Notion Mcp Server

Cloud MCP Server for Notion. Connect AI agents (Claude, GPT, Cursor) to your Notion workspace with 20 API operations for pages, databases, blocks, and comments.

Features

• 20 Operations - Full Notion API coverage
• Demo Mode - Test without authentication
• URL Support - Accept Notion URLs or IDs
• Pagination - Handle large datasets with cursors
• Error Handling - Clear messages with API codes

Quick Start

Demo Mode (No Setup)

{
  "operation": "demo"
}

Search Your Workspace

{
  "notionToken": "ntn_your_token_here",
  "operation": "search",
  "query": "Meeting Notes"
}

Setup

1. Create a Notion Integration

1. Go to notion.so/profile/integrations
2. Click New integration
3. Name it (e.g., "Apify MCP")
4. Copy the token (starts with ntn_)

2. Share Pages with Integration

For each page/database you want to access:

1. Open the page in Notion
2. Click ... menu → Connections
3. Select your integration

Input Parameters

Parameter	Type	Description
notionToken	string	Notion API token (ntn_ or secret_)
operation	string	API operation to perform
query	string	Search query text
pageId	string	Page ID or Notion URL
databaseId	string	Database ID or URL
blockId	string	Block ID or URL
userId	string	User ID
parentPageId	string	Parent page for new pages
parentDatabaseId	string	Parent database for entries
title	string	Title for new pages/databases
properties	string	JSON properties for create/update
children	string	JSON block children to append
filter	string	JSON filter for queries
sorts	string	JSON sort configuration
startCursor	string	Pagination cursor
pageSize	integer	Results per page (max 100)

Operations

Search & Discovery

Operation	Description	Required
demo	Test without token	-
search	Find pages/databases	query

Pages

Operation	Description	Required
get_page	Get page details	pageId
create_page	Create page	parentPageId or parentDatabaseId, title
update_page	Update properties	pageId, properties
archive_page	Archive page	pageId
get_page_property	Get property value	pageId, propertyId

Databases

Operation	Description	Required
get_database	Get schema	databaseId
query_database	Query rows	databaseId
create_database	Create database	parentPageId, title
update_database	Update database	databaseId

Blocks

Operation	Description	Required
get_block	Get block content	blockId
get_block_children	Get children	blockId
append_block_children	Add blocks	blockId, children
update_block	Update block	blockId
delete_block	Delete block	blockId

Comments & Users

Operation	Description	Required
get_comments	Get comments	blockId
create_comment	Add comment	pageId, richText
list_users	List workspace users	-
get_user	Get user details	userId
get_bot_user	Get integration info	-

Examples

Search Pages

{
  "notionToken": "ntn_xxx",
  "operation": "search",
  "query": "Project Plan"
}

Get Page by URL

{
  "notionToken": "ntn_xxx",
  "operation": "get_page",
  "pageId": "https://notion.so/My-Page-abc123def456"
}

Query Database with Filter

{
  "notionToken": "ntn_xxx",
  "operation": "query_database",
  "databaseId": "abc123",
  "filter": "{\"property\":\"Status\",\"select\":{\"equals\":\"Done\"}}"
}

Create Page with Content

{
  "notionToken": "ntn_xxx",
  "operation": "create_page",
  "parentPageId": "parent-id",
  "title": "New Page",
  "children": "[{\"object\":\"block\",\"type\":\"paragraph\",\"paragraph\":{\"rich_text\":[{\"type\":\"text\",\"text\":{\"content\":\"Hello world!\"}}]}}]"
}

Output Schema

Field	Type	Description
operation	string	Operation performed
success	boolean	Success status
objectType	string	Notion object type
objectId	string	Primary object ID
content	object	Returned data
resultCount	integer	Number of results
hasMore	boolean	More results available
nextCursor	string	Pagination cursor
error	string	Error message
errorCode	string	Notion API error code

Success Response

{
  "operation": "search",
  "success": true,
  "objectType": "search_results",
  "content": [...],
  "resultCount": 10,
  "hasMore": false
}

Error Response

{
  "operation": "get_page",
  "success": false,
  "error": "[object_not_found] Could not find page",
  "errorCode": "object_not_found"
}

MCP Integration

Claude Desktop

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@anthropic/apify-mcp-client", "constant_quadruped/notion-mcp-server"]
    }
  }
}

Apify Client (JavaScript)

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: 'YOUR_APIFY_TOKEN' });

const run = await client.actor('constant_quadruped/notion-mcp-server').call({
  notionToken: 'ntn_xxx',
  operation: 'search',
  query: 'Meeting Notes'
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);

Apify Client (Python)

from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")

run = client.actor("constant_quadruped/notion-mcp-server").call(run_input={
    "notionToken": "ntn_xxx",
    "operation": "search",
    "query": "Meeting Notes"
})

items = client.dataset(run["defaultDatasetId"]).list_items().items
print(items)

Troubleshooting

Issue	Solution
"API token is invalid"	Token must start with ntn_ or secret_. Regenerate at notion.so/profile/integrations
"Could not find object"	Add integration to page: ... → Connections → Select integration
Rate limiting	Notion allows 3 req/sec. Use pagination for large datasets

Resources

• Notion API Docs
• Create Integration
• Block Types
• Model Context Protocol

License

MIT