Notion MCP Server
MCP Server for the Notion API, enabling LLM to interact with Notion workspaces. Additionally, it employs Markdown conversion to reduce context size when communicating with LLMs, optimizing token usage and making interactions more efficient.
Setup
Here is a detailed explanation of the steps mentioned above in the following articles:
- Japanese Version: https://qiita.com/suekou/items/44c864583f5e3e6325d9
- Create a Notion Integration:
- Retrieve the Secret Key:
- Add the Integration to Your Workspace:
- Configure Claude Desktop:
Add the following to your
claude_desktop_config.json:
or
Environment Variables
NOTION_API_TOKEN(required): Your Notion API integration token.
NOTION_MARKDOWN_CONVERSION: Set to "true" to enable experimental Markdown conversion. This can significantly reduce token consumption when viewing content, but may cause issues when trying to edit page content.
Command Line Arguments
--enabledTools: Comma-separated list of tools to enable (e.g. "notion_retrieve_page,notion_query_database"). When specified, only the listed tools will be available. If not specified, all tools are enabled.
Read-only tools example (copy-paste friendly):
Advanced Configuration
Markdown Conversion
By default, all responses are returned in JSON format. You can enable experimental Markdown conversion to reduce token consumption:
or
When
NOTION_MARKDOWN_CONVERSION is set to "true", responses will be converted to Markdown format (when format parameter is set to "markdown"), making them more human-readable and significantly reducing token consumption. However, since this feature is experimental, it may cause issues when trying to edit page content as the original structure is lost in conversion.You can control the format on a per-request basis by setting the
format parameter to either "json" or "markdown" in your tool calls:- Use
"markdown"for better readability when only viewing content
- Use
"json"when you need to modify the returned content
Troubleshooting
If you encounter permission errors:
- Ensure the integration has the required permissions.
- Verify that the integration is invited to the relevant pages or databases.
- Confirm the token and configuration are correctly set in
claude_desktop_config.json.
Project Structure
The project is organized in a modular way to improve maintainability and readability:
Directory Descriptions
- index.ts: Application entry point. Parses command-line arguments and starts the server.
- client/: Module responsible for communication with the Notion API.
- server/: MCP server implementation.
- types/: Type definition module.
- utils/: Utility functions.
- markdown/: Markdown conversion functionality.
Tools
All tools support the following optional parameter:
format(string, "json" or "markdown", default: "markdown"): Controls the response format. Use "markdown" for human-readable output, "json" for programmatic access to the original data structure. Note: Markdown conversion only works when theNOTION_MARKDOWN_CONVERSIONenvironment variable is set to "true".
notion_append_block_children
notion_retrieve_block
notion_retrieve_block_children
notion_delete_block
notion_retrieve_page
notion_update_page_properties
notion_create_database
notion_query_database
notion_retrieve_database
notion_update_database
notion_create_database_item
notion_search
notion_list_all_users
notion_retrieve_user
notion_retrieve_bot_user
notion_create_comment
notion_retrieve_comments
License
This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.
Notion MCP Server
MCP Server for the Notion API, enabling LLM to interact with Notion workspaces. Additionally, it employs Markdown conversion to reduce context size when communicating with LLMs, optimizing token usage and making interactions more efficient.
Setup
Here is a detailed explanation of the steps mentioned above in the following articles:
- Japanese Version: https://qiita.com/suekou/items/44c864583f5e3e6325d9
- Create a Notion Integration:
- Retrieve the Secret Key:
- Add the Integration to Your Workspace:
- Configure Claude Desktop:
Add the following to your
claude_desktop_config.json:
or
Environment Variables
NOTION_API_TOKEN(required): Your Notion API integration token.
NOTION_MARKDOWN_CONVERSION: Set to "true" to enable experimental Markdown conversion. This can significantly reduce token consumption when viewing content, but may cause issues when trying to edit page content.
Command Line Arguments
--enabledTools: Comma-separated list of tools to enable (e.g. "notion_retrieve_page,notion_query_database"). When specified, only the listed tools will be available. If not specified, all tools are enabled.
Read-only tools example (copy-paste friendly):
Advanced Configuration
Markdown Conversion
By default, all responses are returned in JSON format. You can enable experimental Markdown conversion to reduce token consumption:
or
When
NOTION_MARKDOWN_CONVERSION is set to "true", responses will be converted to Markdown format (when format parameter is set to "markdown"), making them more human-readable and significantly reducing token consumption. However, since this feature is experimental, it may cause issues when trying to edit page content as the original structure is lost in conversion.You can control the format on a per-request basis by setting the
format parameter to either "json" or "markdown" in your tool calls:- Use
"markdown"for better readability when only viewing content
- Use
"json"when you need to modify the returned content
Troubleshooting
If you encounter permission errors:
- Ensure the integration has the required permissions.
- Verify that the integration is invited to the relevant pages or databases.
- Confirm the token and configuration are correctly set in
claude_desktop_config.json.
Project Structure
The project is organized in a modular way to improve maintainability and readability:
Directory Descriptions
- index.ts: Application entry point. Parses command-line arguments and starts the server.
- client/: Module responsible for communication with the Notion API.
- server/: MCP server implementation.
- types/: Type definition module.
- utils/: Utility functions.
- markdown/: Markdown conversion functionality.
Tools
All tools support the following optional parameter:
format(string, "json" or "markdown", default: "markdown"): Controls the response format. Use "markdown" for human-readable output, "json" for programmatic access to the original data structure. Note: Markdown conversion only works when theNOTION_MARKDOWN_CONVERSIONenvironment variable is set to "true".
notion_append_block_children
notion_retrieve_block
notion_retrieve_block_children
notion_delete_block
notion_retrieve_page
notion_update_page_properties
notion_create_database
notion_query_database
notion_retrieve_database
notion_update_database
notion_create_database_item
notion_search
notion_list_all_users
notion_retrieve_user
notion_retrieve_bot_user
notion_create_comment
notion_retrieve_comments
License
This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.