📌Overview

Purpose: To enable Claude to interact seamlessly with Notion workspaces using the MCP Server for the Notion API.

Overview: The Notion MCP Server facilitates the integration of Claude with Notion, allowing users to manage and manipulate Notion content programmatically. This server provides a straightforward setup process, making it easy to authenticate and configure necessary tools for enhanced interaction with Notion's features.

Key Features:

Integration Setup: Simplifies creating a Notion integration, retrieving API tokens, and adding the integration to the workspace, enhancing accessibility and ease of use.
Experimental Markdown Conversion: Offers an option to convert responses to Markdown format, reducing token consumption and improving readability for viewing content while maintaining the capability to retrieve data in JSON for modifications.

Notion MCP Server

MCP Server for the Notion API, enabling LLMs to interact with Notion workspaces. It employs Markdown conversion to reduce context size when communicating with LLMs, optimizing token usage and making interactions more efficient.

Setup

Detailed setup guides:

English Version: https://dev.to/suekou/operating-notion-via-claude-desktop-using-mcp-c0h
Japanese Version: https://qiita.com/suekou/items/44c864583f5e3e6325d9

Steps

Create a Notion Integration
- Visit the Notion Your Integrations page: https://www.notion.so/profile/integrations
- Click "New Integration".
- Name your integration and select appropriate permissions (e.g., "Read content", "Update content").
Retrieve the Secret Key
- Copy the "Internal Integration Token" from your integration to use for authentication.
Add the Integration to Your Workspace
- Open the page or database you want the integration to access.
- Click the "···" button in the top right corner.
- Click "Connections" and select your created integration.
Configure Claude Desktop
Add the following in your claude_desktop_config.json:

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@suekou/mcp-notion-server"],
      "env": {
        "NOTION_API_TOKEN": "your-integration-token"
      }
    }
  }
}

{
  "mcpServers": {
    "notion": {
      "command": "node",
      "args": ["your-built-file-path"],
      "env": {
        "NOTION_API_TOKEN": "your-integration-token"
      }
    }
  }
}

Environment Variables

NOTION_API_TOKEN (required): Your Notion API integration token.
NOTION_MARKDOWN_CONVERSION: Set to "true" to enable experimental Markdown conversion to reduce token consumption when viewing content. This may cause issues when editing page content.

Command Line Arguments

--enabledTools: Comma-separated list of tools to enable (e.g. "notion_retrieve_page,notion_query_database"). When specified, only listed tools are enabled; otherwise, all tools are enabled.

Example for read-only tools:

node build/index.js --enabledTools=notion_retrieve_block,notion_retrieve_block_children,notion_retrieve_page,notion_query_database,notion_retrieve_database,notion_search,notion_list_all_users,notion_retrieve_user,notion_retrieve_bot_user,notion_retrieve_comments

Advanced Configuration

Markdown Conversion

By default, responses are returned in JSON. To enable experimental Markdown conversion to reduce token usage, set environment variable NOTION_MARKDOWN_CONVERSION to "true":

Example config with Markdown conversion enabled:

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@suekou/mcp-notion-server"],
      "env": {
        "NOTION_API_TOKEN": "your-integration-token",
        "NOTION_MARKDOWN_CONVERSION": "true"
      }
    }
  }
}

With "markdown" format set in requests, responses will be more human-readable and use fewer tokens. Use "json" format to preserve original data structure for editing.

Troubleshooting

If you encounter permission errors:

Ensure the integration has required permissions.
Verify the integration is invited to relevant pages or databases.
Confirm correct token and configuration in claude_desktop_config.json.

Project Structure

./
├── src/
│   ├── index.ts              # Entry point and CLI handling
│   ├── client/
│   │   └── index.ts          # NotionClientWrapper class for API calls
│   ├── server/
│   │   └── index.ts          # MCP server and request handling
│   ├── types/
│   │   ├── index.ts          # Type exports
│   │   ├── args.ts           # Tool argument interfaces
│   │   ├── common.ts         # Common schema definitions
│   │   ├── responses.ts      # Notion API response types
│   │   └── schemas.ts        # MCP tool schemas
│   ├── utils/
│   │   └── index.ts          # Utility functions
│   └── markdown/
│       └── index.ts          # Markdown conversion utilities

Directory Summary

index.ts: Application entry point, parses CLI arguments and starts server.
client/: Handles Notion API communication.
server/: MCP server implementation, processes requests.
types/: Type definitions and interfaces.
utils/: Utility functions.
markdown/: Converts JSON responses to Markdown format.

Tools

All tools support an optional parameter:

format (string, "json" or "markdown", default: "markdown"): Controls response format. Markdown conversion requires NOTION_MARKDOWN_CONVERSION to be "true".

Available Tools

notion_append_block_children
Append child blocks to a parent block.
Inputs: block_id (string), children (array).
Returns info on appended blocks.
notion_retrieve_block
Retrieve a specific block.
Input: block_id (string). Returns detailed block info.
notion_retrieve_block_children
Retrieve children of a block.
Inputs: block_id (string), optional start_cursor (string), page_size (number, default 100).
Returns list of child blocks.
notion_delete_block
Delete a block.
Input: block_id (string). Returns confirmation.
notion_retrieve_page
Retrieve a specific page.
Input: page_id (string). Returns detailed page info.
notion_update_page_properties
Update page properties.
Inputs: page_id (string), properties (object). Returns updated page info.
notion_create_database
Create a database.
Inputs: parent (object), properties (object), optional title (array). Returns created database info.
notion_query_database
Query a database.
Inputs: database_id (string), optional filter (object), sorts (array), start_cursor (string), page_size (number, default 100). Returns query results.
notion_retrieve_database
Retrieve database info.
Input: database_id (string).
notion_update_database
Update database info.
Inputs: database_id (string), optional title (array), description (array), properties (object).
notion_create_database_item
Create a new item in a database.
Inputs: database_id (string), properties (object). Returns new item info.
notion_search
Search pages or databases by title.
Optional inputs: query (string), filter (object), sort (object), start_cursor (string), page_size (number, default 100).
notion_list_all_users
List all users in workspace. Requires Notion Enterprise plan and Organization API key.
Optional inputs: start_cursor (string), page_size (max 100).
notion_retrieve_user
Retrieve a specific user by user_id (string). Requires Notion Enterprise plan and Organization API key.
notion_retrieve_bot_user
Retrieve bot user linked to current token.
notion_create_comment
Create a comment (requires insert comment permission). Specify either a parent object with page_id or a discussion_id.
Inputs: rich_text (array), optional parent (with page_id), or discussion_id (string).
notion_retrieve_comments
Retrieve unresolved comments of a page or block (requires read comment permission).
Inputs: block_id (string), optional start_cursor (string), page_size (max 100).

License

Licensed under the MIT License. You are free to use, modify, and distribute the software under the terms of the MIT License. See the LICENSE file in the project repository for details.