README.md
Comprehensive tools to interact with the Notion API via OAuth2 authentication
notion-mcp
A Notion MCP server using OAuth2 bearer token auth via the Dedalus framework.
Features
This MCP server provides tools to interact with the Notion API:
User Tools
notion_get_user- Retrieve a specific user by IDnotion_list_users- List all users in the workspacenotion_get_self- Get the authenticated bot user's information
Search Tools
notion_search- Search pages and databases by title
Block Tools
notion_get_block- Retrieve a block by IDnotion_get_block_children- Get child blocks of a parentnotion_append_block_children- Append new blocks to a parentnotion_update_block- Update a block's contentnotion_delete_block- Delete (archive) a block
Page Tools
notion_get_page- Get a page's metadata and propertiesnotion_get_page_property- Get a specific property from a pagenotion_create_page- Create a new pagenotion_update_page- Update a page's properties
Comment Tools
notion_get_comments- Retrieve comments from a page or blocknotion_create_comment- Create a comment on a page
Database Tools
notion_query_database- Query a database with filters and sortsnotion_get_database- Get database metadata and schemanotion_update_database- Update database propertiesnotion_create_database- Create a new database
Installation
# Clone the repository
git clone https://github.com/dedalus-labs/notion-mcp.git
cd notion-mcp
# Install dependencies with uv
uv sync
Configuration
Copy .env.example to .env and configure:
cp .env.example .env
OAuth Configuration
The Notion API requires OAuth2 authentication. The access token is provided at runtime via Dedalus credential exchange.
Required OAuth scopes depend on your use case:
- Read content: Basic integration capabilities
- Insert content: Create pages and blocks
- Update content: Modify existing content
- Read user information (without email): List users
Usage
Running Locally
cd notion-mcp
uv sync
uv run python src/main.py
The server will start on port 8080.
With Dedalus Platform
In your chat, reference the server with @notion-mcp followed by your instructions:
@notion-mcp Search for all pages containing "meeting notes"
@notion-mcp Create a new page titled "Project Plan" in my workspace
Development
Running Tests
uv run pytest
Linting
uv run ruff check src/
uv run ruff format src/
License
MIT License - see LICENSE for details.
Tools (19)
notion_get_userRetrieve a specific user by IDnotion_list_usersList all users in the workspacenotion_get_selfGet the authenticated bot user's informationnotion_searchSearch pages and databases by titlenotion_get_blockRetrieve a block by IDnotion_get_block_childrenGet child blocks of a parentnotion_append_block_childrenAppend new blocks to a parentnotion_update_blockUpdate a block's contentnotion_delete_blockDelete (archive) a blocknotion_get_pageGet a page's metadata and propertiesnotion_get_page_propertyGet a specific property from a pagenotion_create_pageCreate a new pagenotion_update_pageUpdate a page's propertiesnotion_get_commentsRetrieve comments from a page or blocknotion_create_commentCreate a comment on a pagenotion_query_databaseQuery a database with filters and sortsnotion_get_databaseGet database metadata and schemanotion_update_databaseUpdate database propertiesnotion_create_databaseCreate a new databaseEnvironment Variables
NOTION_ACCESS_TOKENrequiredOAuth2 bearer token provided via Dedalus credential exchangeConfiguration
claude_desktop_config.json
{"mcpServers":{"notion-mcp":{"command":"uv","args":["run","python","src/main.py"],"env":{"NOTION_ACCESS_TOKEN":"<your-token>"}}}}Try it
→Search for all pages containing 'meeting notes'
→Create a new page titled 'Project Plan' in my workspace
→List all users in my Notion workspace
→Query my database for all items with a 'High' priority filter
→Add a comment to the block with ID 123 saying 'Please review this section'