Integrations
Allows running the MCP server as a Docker container, providing an alternative deployment method to the npm package.
Provides a read-only interface to the Notion API, allowing retrieval of pages, blocks, databases, comments and properties. Features include parallel processing of requests, recursive page retrieval, and optimized content exploration for AI assistants.
Notion ReadOnly MCP Server
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.
Key Improvements
- 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.
Tool Comparison
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.
Installation
1. Setting up Integration in Notion:
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:
2. Adding MCP config to your client:
Using npm:
Add the following to your .cursor/mcp.json
or claude_desktop_config.json
(MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
)
Using Docker:
Add the following to your .cursor/mcp.json
or claude_desktop_config.json
:
Don't forget to replace ntn_****
with your integration secret. Find it from your integration configuration tab.
3. Connecting content to integration:
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".
Available Tools
This optimized server exposes only essential read-only Notion API tools:
API-retrieve-a-page
: Get page informationAPI-get-block-children
: Get page content blocks (with parallel processing)API-retrieve-a-block
: Get details about a specific blockAPI-retrieve-a-database
: Get database informationAPI-retrieve-a-comment
: Get comments on a page or blockAPI-retrieve-a-page-property
: Get specific property information from a pageAPI-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
Automatic Content Exploration
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
Using One Pager Tool
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.
Asynchronous Processing
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
Examples
- Using the following instruction:
The AI will retrieve the page details efficiently with parallel processing of block content.
- Using database information:
Development
Build:
Execute:
License
MIT
AI Assistant Performance Benefits
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
You must be authenticated.
Tools
An optimized read-only server for AI assistants to efficiently query and retrieve Notion content, featuring parallel processing and a minimized toolset of 7 essential read-only operations.
- Key Improvements
- Tool Comparison
- Installation
- Available Tools
- Automatic Content Exploration
- Asynchronous Processing
- Examples
- Development
- License
- AI Assistant Performance Benefits
Related Resources
Related MCP Servers
- AsecurityAlicenseAqualityAllows AI assistants to list tables, read data, and execute SQL queries through a controlled interface, making database exploration and analysis safer and more structured.Last updated -1360PythonMIT License
Tavily MCP Serverofficial
AsecurityAlicenseAqualityThis server enables AI systems to integrate with Tavily's search and data extraction tools, providing real-time web information access and domain-specific searches.Last updated -25,133334JavaScriptMIT License- -securityFlicense-qualityEnables AI assistants to interact with Metabase, providing access to dashboards, questions, databases, and tools for executing queries and viewing data through natural language.Last updated -JavaScript
Notion MCP Serverofficial
AsecurityAlicenseAqualityAn MCP server that enables AI assistants to interact with the Notion API, allowing them to search, read, comment on, and create content in Notion workspaces through natural language commands.Last updated -195,6171,472TypeScriptMIT License