Which integrations are available for this server?

Provides full CRUD capabilities over Notion pages, databases, and content blocks, enabling management of Notion content programmatically.

How do I use cs-ai-notion-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. 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

by trilogy-group

Overview Schema Source Related Servers Discussions Admin

JavaScript

Remote

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 install

3. Environment Configuration

Copy .env.example to .env and set your key:

cp .env.example .env

Edit .env:

NOTION_API_KEY=secret_your_actual_notion_api_token

Running the Server

Local Execution (stdio)

npm start

Testing with MCP Inspector

npx @modelcontextprotocol/inspector node index.mjs

Adding 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 tools

append_blocksD

ParametersJSON Schema

Name	Required	Description	Default
`block_id`	Yes	ID of the target page or block
`text_lines`	Yes	Array of text lines to append as paragraph blocks

TDQS

D1/5.0

Behavior1/5

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

Tool has no description.

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

Conciseness1/5

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

Tool has no description.

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

Completeness1/5

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

Tool has no description.

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

Parameters1/5

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

Tool has no description.

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

Purpose1/5

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

Tool has no description.

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

Usage Guidelines1/5

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

Tool has no description.

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

create_pageD

ParametersJSON Schema

Name	Required	Description	Default
`title`	Yes	Title of the new page
`parent_id`	Yes	ID of the parent page or database
`parent_type`	No	Type of parent entity	page_id
`content_body`	No	Initial paragraph content body for the new page

TDQS

D1/5.0

Behavior1/5

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

Tool has no description.

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

Conciseness1/5

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

Tool has no description.

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

Completeness1/5

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

Tool has no description.

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

Parameters1/5

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

Tool has no description.

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

Purpose1/5

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

Tool has no description.

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

Usage Guidelines1/5

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

Tool has no description.

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

delete_pageD

ParametersJSON Schema

Name	Required	Description	Default
`page_id`	Yes	ID of the page to delete (archive)

TDQS

D1/5.0

Behavior1/5

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

Tool has no description.

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

Conciseness1/5

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

Tool has no description.

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

Completeness1/5

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

Tool has no description.

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

Parameters1/5

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

Tool has no description.

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

Purpose1/5

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

Tool has no description.

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

Usage Guidelines1/5

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

Tool has no description.

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

get_pageD

ParametersJSON Schema

Name	Required	Description	Default
`page_id`	Yes	The ID of the Notion page to retrieve

TDQS

D1/5.0

Behavior1/5

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

Tool has no description.

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

Conciseness1/5

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

Tool has no description.

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

Completeness1/5

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

Tool has no description.

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

Parameters1/5

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

Tool has no description.

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

Purpose1/5

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

Tool has no description.

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

Usage Guidelines1/5

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

Tool has no description.

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

get_page_blocksD

ParametersJSON Schema

Name	Required	Description	Default
`block_id`	Yes	ID of the page or block to read children from
`page_size`	No	Maximum number of blocks to return

TDQS

D1/5.0

Behavior1/5

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

Tool has no description.

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

Conciseness1/5

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

Tool has no description.

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

Completeness1/5

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

Tool has no description.

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

Parameters1/5

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

Tool has no description.

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

Purpose1/5

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

Tool has no description.

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

Usage Guidelines1/5

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

Tool has no description.

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

search_pagesD

ParametersJSON Schema

Name	Required	Description	Default
`query`	No	Search keyword to find pages or databases
`filter_type`	No	Filter by 'page' or 'database'

TDQS

D1/5.0

Behavior1/5

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

Tool has no description.

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

Conciseness1/5

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

Tool has no description.

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

Completeness1/5

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

Tool has no description.

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

Parameters1/5

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

Tool has no description.

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

Purpose1/5

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

Tool has no description.

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

Usage Guidelines1/5

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

Tool has no description.

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

update_pageD

ParametersJSON Schema

Name	Required	Description	Default
`page_id`	Yes	ID of the page to update
`archived`	No	Set true to archive/delete the page, false to unarchive

TDQS

D1/5.0

Behavior1/5

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

Tool has no description.

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

Conciseness1/5

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

Tool has no description.

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

Completeness1/5

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

Tool has no description.

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

Parameters1/5

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

Tool has no description.

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

Purpose1/5

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

Tool has no description.

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

Usage Guidelines1/5

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

Tool has no description.

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.

7 tool updatesv1.0.0Aug 4, 2026
- First observedappend_blocks
- First observedcreate_page
- First observeddelete_page
- First observedget_page
- First observedget_page_blocks
- First observedsearch_pages
- First observedupdate_page

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

C2.1/5.0

Scored 2026-08-04 16:40 across 7 tools

Disambiguation5/5

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.

Naming Consistency5/5

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.

Tool Count5/5

With 7 tools, the set is well-scoped for a Notion page management server. Each tool covers a core operation without redundancy or bloat.

Completeness4/5

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.

Maintenance

ActivitySlowing

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

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
kesslerio-attio-mcp-server-betaOAuth
ai.smithery
Streamline your Attio workflows using natural language to search, create, update, and organize com…
Customer Data Platforms App Automation Workplace & Productivity
269
KnowtisOAuth
app.knowtis
Create, search and manage Knowtis collaborative notes from AI assistants.
Note Taking Knowledge & Memory
21
xNotepad AI
com.xnotepadai
Create, search, and update notes in an xNotepad AI notebook, with semantic search and AI Q&A.
Note Taking AI & Machine Learning Knowledge & Memory
1

Related MCP Servers

Notion MCP Server
Content Management Systems Developer Tools Note Taking
michaelwaves
F
license
B
quality
D
maintenance
Enables 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.
Updated a year ago (2025-08-24 01:18 UTC)
4
-
Notion MCP Server
Workplace & Productivity Content Management Systems Note Taking
riteshtk
A
license
Not graded
quality
D
maintenance
Enables interaction with Notion workspaces through the Notion API, allowing users to search, read, comment on, and create pages and databases using natural language commands.
Updated a year ago (2025-05-11 18:02 UTC)
122,532 npm
MIT
Notion Weaver
Workplace & Productivity Content Management Systems App Automation
consigcody94
A
license
Not graded
quality
Not graded
maintenance
Enables AI workflows to integrate with Notion workspaces, supporting page and database creation, queries with filters and sorting, content updates, and workspace-wide search operations.
Updated 10 months ago (2025-11-22 02:02 UTC)
-
Notion MCP Server
Workplace & Productivity Content Management Systems Note Taking
KevinDigran97
A
license
Not graded
quality
D
maintenance
Enables 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.
Updated 8 months ago (2026-01-02 12:58 UTC)
122,532 npm
MIT