This project implements an optimized read-only MCP server for the Notion API, focusing on performance and efficiency for AI assistants to query and retrieve Notion content.
- Read-Only Design: Focused exclusively on data retrieval operations, ensuring safe access to Notion content.
- Minimized Tool Set: Reduced the number of exposed Notion API tools from 15+ to only 6 essential ones for document analysis.
- Parallel Processing: Enhanced performance by implementing asynchronous and parallel API requests for retrieving block content, significantly reducing response times.
- Extended Database Access: Added support for database, page property, and comment retrieval operations.
- Optimized for AI Assistants: Significantly reduced tool count addresses the "Too many tools can degrade performance" issue in AI assistants like Cursor, which limits models to approximately 40 tools.
This read-only implementation exposes far fewer tools compared to the standard Notion API integration, improving performance and compatibility with AI assistants:
The reduced tool set helps stay within the recommended tool limits for optimal AI assistant performance while still providing all essential functionality.
Go to https://www.notion.so/profile/integrations and create a new internal integration or select an existing one.
While we limit the scope of Notion API's exposed to read-only operations, there is a non-zero risk to workspace data by exposing it to LLMs. Security-conscious users may want to further configure the Integration's Capabilities.
For example, you can create a read-only integration token by giving only "Read content" access from the "Configuration" tab:
Add the following to your .cursor/mcp.json or claude_desktop_config.json (MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json)
{
"mcpServers": {
"notionApi": {
"command": "npx",
"args": ["-y", "notion-readonly-mcp-server"],
"env": {
"OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2022-06-28\" }"
}
}
}
}Add the following to your .cursor/mcp.json or claude_desktop_config.json:
{
"mcpServers": {
"notionApi": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e", "OPENAPI_MCP_HEADERS",
"taewoong1378/notion-readonly-mcp-server"
],
"env": {
"OPENAPI_MCP_HEADERS": "{\"Authorization\":\"Bearer ntn_****\",\"Notion-Version\":\"2022-06-28\"}"
}
}
}
}Don't forget to replace ntn_**** with your integration secret. Find it from your integration configuration tab.
Ensure relevant pages and databases are connected to your integration.
To do this, visit the page, click on the 3 dots, and select "Connect to integration".
This optimized server exposes only essential read-only Notion API tools:
-
API-retrieve-a-page: Get page information -
API-get-block-children: Get page content blocks (with parallel processing) -
API-retrieve-a-block: Get details about a specific block -
API-retrieve-a-database: Get database information -
API-retrieve-a-comment: Get comments on a page or block -
API-retrieve-a-page-property: Get specific property information from a page -
API-get-one-pager: NEW! Recursively retrieve a full Notion page with all its blocks, databases, and related content in a single call
By limiting to these 7 essential tools (compared to 15+ in the standard implementation), we ensure:
- Better performance in AI assistants like Cursor and Claude that have tool count limitations
- Reduced cognitive load for AI models when choosing appropriate tools
- Faster response times with fewer API options to consider
- Enhanced security through minimized API surface area
The new API-get-one-pager tool provides a powerful way to explore Notion pages without requiring multiple API calls:
- Recursive retrieval: Automatically traverses the entire page structure including nested blocks
- Parallel processing: Fetches multiple blocks and their children simultaneously for maximum performance
- Intelligent caching: Stores retrieved data to minimize redundant API calls
- Comprehensive content: Includes pages, blocks, databases, comments, and detailed property information
- Customizable depth: Control the level of recursion to balance between detail and performance
{
"page_id": "YOUR_PAGE_ID",
"maxDepth": 5, // Optional: Maximum recursion depth (default: 5)
"includeDatabases": true, // Optional: Include linked databases (default: true)
"includeComments": true, // Optional: Include comments (default: true)
"includeProperties": true // Optional: Include detailed page properties (default: true)
}
This automatic exploration capability is especially useful for AI assistants that need to understand the entire content of a Notion page without making dozens of separate API calls, resulting in much faster and more efficient responses.
The server implements advanced parallel processing techniques for handling large Notion documents:
- Multiple requests are batched and processed concurrently
- Pagination is handled automatically for block children
- Results are efficiently aggregated before being returned
- Console logging provides visibility into the process without affecting response format
- Using the following instruction:
Get the content of page 1a6b35e6e67f802fa7e1d27686f017f2
The AI will retrieve the page details efficiently with parallel processing of block content.
- Using database information:
Get the structure of database 8a6b35e6e67f802fa7e1d27686f017f2
Build:
pnpm build
Execute:
pnpm dev
MIT
Modern AI assistants like Cursor and Claude have limitations on the number of tools they can effectively handle:
- Most models may not respect more than 40 tools in total
- Too many tools can degrade overall performance and reasoning capabilities
- Complex tool sets increase response latency and decision-making difficulty
This read-only implementation deliberately reduces the Notion API surface to address these limitations while preserving all essential functionality. The result is:
- Faster and more reliable responses from AI assistants
- Improved accuracy when interacting with Notion content
- Better overall performance through focused API design