home / mcp / better notion mcp server

Better Notion MCP Server

Provides a Notion integration driven by a single Markdown document to read, create, and update Notion pages via MCP.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "ai-aviate-better-mcp-notion": {
      "command": "npx",
      "args": [
        "-y",
        "better-mcp-notion"
      ],
      "env": {
        "NOTION_API_KEY": "ntn_your_api_key_here"
      }
    }
  }
}

You can operate Notion with a single Markdown document using this MCP server. It reads, creates, and updates Notion pages in one call, reducing round-trips and simplifying workflows for managing pages, databases, and content blocks from Markdown.

How to use

You run this MCP server through an MCP client to perform read, write, and manage actions against Notion. The available tools let you read a Notion page as Markdown, create or update pages from Markdown, search and list workspace content, manage database schemas, and handle comments, deletions, and page moves. When you provide a Markdown document with YAML frontmatter, you can read, create, update, or append content in a single operation.

How to install

Prerequisites: you need Node.js and npm installed on your system.

1) Clone the repository to your machine.

2) Install dependencies.

3) Build the server.

4) Configure your MCP client to run the server using the provided commands.

Examples and configuration

Add the Notion MCP server to your MCP client as a standard MCP server. The following examples show how to use the server in different client environments.

claude mcp add better-notion -- npx better-mcp-notion
```

```bash
export NOTION_API_KEY=ntn_your_api_key_here

Additional setup from source

# From source
git clone https://github.com/ai-aviate/better-mcp-notion.git
cd better-mcp-notion
npm install && npm run build
```

Then point your MCP config to the built runtime

```bash
node /path/to/better-mcp-notion/build/index.js

Available tools

read

Read a Notion page and return Markdown with YAML frontmatter. Supports recursive child page reading with a depth parameter.

write

Create or update pages from Markdown, supporting batch operations and options to append or prepend content.

search

Search the workspace by keyword and return results in Markdown format.

list

List database records as a table or child pages as a list, with natural language filters and sorts.

update

Quickly update page properties without rewriting the content.

schema

View, add, rename, or remove database schema columns.

comment

Read or add comments on a page.

delete

Archive pages (soft-delete).

move

Move a page to a different parent page or database.