cs-ai-notion-mcp
Provides full CRUD capabilities over Notion pages, databases, and content blocks, enabling management of Notion content programmatically.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@cs-ai-notion-mcp Create a new task in my Tasks database"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
cs-ai-notion-mcp
A custom Model Context Protocol (MCP) server for Notion providing full CRUD (Create, Read, Update, Delete) capabilities over Notion pages, databases, and content blocks. Built using FastMCP (@modelcontextprotocol/sdk) and the official Notion JavaScript SDK (@notionhq/client).
Features
🔍
search_pages: Search pages or databases in your Notion workspace.📖
get_page: Retrieve metadata and properties for a specific page.📝
create_page: Create new pages under existing pages or database entries.✏️
update_page: Update page properties or toggle archive status.🧱
get_page_blocks: Read child content blocks (paragraphs, lists, headings) from a page.➕
append_blocks: Append new content blocks to a page or block.🗑️
delete_page: Archive/delete a page from Notion.
Related MCP server: Notion MCP Server
Setup & Installation
1. Prerequisites
Node.js >= 18
A Notion Integration Token (
NOTION_API_KEY) created at https://www.notion.so/my-integrations.Share target pages or databases with your Notion integration in Notion UI.
2. Installation
cd /Users/xavier.villarroel/GitHub/cs-ai-notion-mcp
npm install3. Environment Configuration
Copy .env.example to .env and set your key:
cp .env.example .envEdit .env:
NOTION_API_KEY=secret_your_actual_notion_api_tokenRunning the Server
Local Execution (stdio)
npm startTesting with MCP Inspector
npx @modelcontextprotocol/inspector node index.mjsAdding to MCP Config (e.g. Claude Desktop or Antigravity)
{
"mcpServers": {
"notion": {
"command": "node",
"args": ["/Users/xavier.villarroel/GitHub/cs-ai-notion-mcp/index.mjs"],
"env": {
"NOTION_API_KEY": "secret_your_actual_notion_api_token"
}
}
}
}Code Architecture
The codebase follows strict project standards with 4 clearly delineated sections in index.mjs:
Import Section: Module dependencies (
@modelcontextprotocol/sdk,@notionhq/client,zod,dotenv).Functions Section: Low-level Notion API operations.
Handler Section: MCP tool definitions and stdio server initialization.
Comments Section: Exhaustive documentation for LLM code comprehension and testing.
License
MIT
Available Tools
7 toolsappend_blocksD
Inputs: block_id (required), text_lines (required).
create_pageD
Inputs: title (required), parent_id (required), parent_type, content_body.
delete_pageD
Inputs: page_id (required).
get_pageD
Inputs: page_id (required).
get_page_blocksD
Inputs: block_id (required), page_size.
search_pagesD
Inputs: query, filter_type.
update_pageD
Inputs: page_id (required), archived.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool focuses on a distinct operation: searching, retrieving, creating, updating, deleting pages, plus fetching and appending blocks. There is no overlap in purpose, and the actions are easily distinguishable.
All tool names follow a consistent verb_noun snake_case pattern (e.g., search_pages, create_page, get_page_blocks). The pattern is uniform and predictable.
With 7 tools, the set is well-scoped for a Notion page management server. Each tool covers a core operation without redundancy or bloat.
The domain covers basic page lifecycle (CRUD + search) and block interactions (get/append). Minor gaps exist (e.g., update/delete blocks), but the core workflows for page management are well covered.
Related MCP Connectors
MCP-native open-source Notion alternative: read & write pages, databases and kanban boards.
Hosted Notion MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Query, explore, and manage your databases through natural conversation.
Streamline your Attio workflows using natural language to search, create, update, and organize com…
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables interaction with Notion workspaces through the Notion API. Supports creating, retrieving, and updating Notion pages and their properties, allowing users to manage Notion content through natural language.4MIT
- AlicenseNot gradedqualityDmaintenanceEnables interaction with Notion workspaces through the Notion API, allowing users to search, read, comment on, and create pages and databases using natural language commands.282,573 npmMIT
- AlicenseNot gradedqualityNot gradedmaintenanceEnables AI workflows to integrate with Notion workspaces, supporting page and database creation, queries with filters and sorting, content updates, and workspace-wide search operations.-
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to interact with Notion workspaces through the Notion API, allowing them to search, read, create, update pages and databases, and manage comments using natural language commands.MIT