Notion AI Gateway

This repository hosts the Notion AI Gateway, an implementation of the Model Context Protocol (MCP) designed to allow advanced AI agents (like LLMs) to manipulate and extract data from a Notion environment. It furnishes a robust set of function calls to govern all major Notion API capabilities, including bulk operations for efficiency.

🚧 Current Focus: Significant advancements have been made in structured data handling (databases) and collaborative features (comments/user lookups). Your support via starring is greatly appreciated to fuel ongoing enhancements.

🗂️ Index

• Initial Setup & Deployment
• Prerequisites
• Client Configuration (Cursor/Claude)
• Core Capabilities
• API Reference
• Exposed Functions
• Available Data Contexts
• Development Flow
• System Architecture
• Debugging Guidance
• Community Contributions
• Licensing Information

🚀 Initial Setup & Deployment

Prerequisites

1. Acquire Notion Credential: Generate an internal integration token from the Notion Developer portal.
2. Grant Workspace Access: Navigate to the target Notion page or database, click the '...' menu, select 'Connections', and activate your newly created integration.
3. Select Execution Method: Proceed with one of the client integration guides below.
4. AI Command Examples:
5. "Fabricate a new daily agenda page."
6. "Synchronize the content of the quarterly review document."
7. "Enrich the existing meeting minutes with the Q&A section."
8. "Provision a structured ledger for Q3 expenditures."
9. "Inject new project tracking records into the master database."
10. "Log an inquiry on the primary project artifact."
11. "Review all active annotations on this workspace item."
12. "Enumerate all workspace participants."
13. "Fetch details for User ID XYZ."

Client Configuration (Cursor/Claude)

Cursor Integration (Using mcp.json Manifest)

Modify or create the configuration file at .cursor/mcp.json:

{ "mcpServers": { "notion-ai-gateway": { "command": "env NOTION_TOKEN=YOUR_TOKEN NOTION_ROOT_ID=YOUR_ID npx", "args": ["-y", "notion-mcp-server"] } } }

Replace YOUR_TOKEN and YOUR_ID with your necessary secret values, then relaunch Cursor.

Claude Desktop Integration (Using mcp.json Configuration)

Update the dedicated configuration file for Claude's environment:

{ "mcpServers": { "notion-ai-gateway": { "command": "npx", "args": ["-y", "notion-mcp-server"], "env": { "NOTION_TOKEN": "YOUR_TOKEN", "NOTION_ROOT_ID": "YOUR_ID" } } } }

Update credentials and restart the Claude application.

🌟 Core Capabilities

• Deep Notion Interoperability: Comprehensive API coverage for documents, blocks, and structured repositories (databases).
• Universal MCP Adherence: Compatible across various clients supporting the Model Context Protocol (e.g., Cursor, Claude Desktop, Zed).
• Data Extraction: Securely retrieve content from Notion pages, structural elements, and database views.
• Content Synthesis: Programmatically generate and modify Notion artifacts.
• Element Management: Advanced control over appending, modifying, and removing content blocks.
• Structured Data Handling: Full lifecycle support for databases: inception, transactional querying, and schema revision.
• Throughput Optimization: Support for vectorized/batch requests to minimize latency.
• State Management: Features for retiring (archiving) and reinstating Notion entities.
• Discovery Services: Title-based searching across pages and associated data structures.
• Annotation Servicing: Management (fetch, post, reply) of comments attached to pages and specific content blocks.
• Identity Resolution: Accessing workspace member lists and individual profile data.

📚 API Reference

The gateway exposes distinct functional modules, each accessible via a designated action within the JSON payload structure.

Exposed Functions

notion_entity_manager (Page Operations)

Manages top-level page entities: - Initiation of new pages with defined content structure. - Alteration of page metadata properties. - Soft deletion (archiving). - Retrieval from the trash bin (restoration). - Title-based lookup services.

Example Payload Structure: javascript { "payload": { "action": "initiate_page", // Options: "initiate_page", "retire_page", "reactivate_page", "lookup_pages", "modify_page_metadata" "params": { / Action-specific arguments / } } }

notion_block_processor (Content Block Operations)

A comprehensive module for granular manipulation of content within pages: - Fetching the raw content of an element. - Enumerating child elements. - Injecting new content fragments. - Modifying existing elements. - Permanent removal of elements. - Executing combined operations (batch append, update, delete, mixed sequencing).

Example Payload Structure: javascript { "payload": { "action": "inject_block_children", // Options: "inject_block_children", "retrieve_element", "enumerate_element_children", "revise_element", "discard_element", "execute_batched_content_updates" "params": { / Action-specific arguments / } } }

notion_data_repository (Database Operations)

Handles the creation and manipulation of structured data containers: - Definition and deployment of new databases, including property schema design. - Executing complex queries against databases using predicates (filters) and ordering sequences. - Schema alteration routines.

Example Payload Structure: javascript { "payload": { "action": "deploy_database", // Options: "deploy_database", "query_data_set", "reconfigure_database_schema" "params": { / Action-specific arguments / } } }

notion_annotation_service (Comment Management)

Tooling dedicated to conversational threads on content: - Retrieval of existing annotations linked to pages or blocks. - Posting new remarks onto pages. - Submitting direct replies within established discussion threads.

Example Payload Structure: javascript { "payload": { "action": "fetch_annotations", // Options: "fetch_annotations", "post_page_annotation", "reply_to_discussion" "params": { / Action-specific arguments / } } }

notion_identity_resolver (User Directory)

Provides access to organizational structure: - Generating a manifest of all active workspace members. - Retrieving detailed attributes for a specified user identifier. - Obtaining metadata for the authorizing integration credential (bot).

Example Payload Structure: javascript { "payload": { "action": "list_members", // Options: "list_members", "resolve_user_profile", "get_integration_identity" "params": { / Action-specific arguments / } } }

Available Data Contexts

The server prioritizes functional tools over exposing static resource endpoints at this time.

🛠 Development Flow

1. Repository Acquisition

git clone https://github.com/awkoy/notion-mcp-server.git cd notion-mcp-server

1. Dependency Installation

npm install

1. Environment Configuration Establish a local .env file containing:

   NOTION_TOKEN=your_master_api_key NOTION_ROOT_ID=your_starting_page_or_db_id

2. Compilation Phase

npm run build

1. Service Inspection

npm run inspector

🔧 System Architecture

• Implemented utilizing modern TypeScript standards, targeting MCP SDK version 1.7.0 and later.
• Leverages the official Notion SDK (@notionhq/client version 2.3.0+).
• Strictly adheres to the Model Context Protocol specification.
• Focuses on providing atomic and vectorized operations across Notion's object hierarchy (pages, blocks, databases).
• Input schema validation is enforced via Zod for robust operation integrity.

❓ Debugging Guidance

• Token/Auth Failures: Verify the API secret is correct and that the associated integration possesses view/edit rights for the targeted workspace entities.
• Access Denied: Confirm the integration has been explicitly invited and enabled on the specific Notion pages/databases being referenced.

• Throttling Issues: If repeated timeouts occur, consolidate sequential operations into the supported batch processing functions to reduce the frequency of external API calls.

• Seeking Assistance

• File an issue on the project's GitHub tracker.
• Consult the comprehensive Notion API Documentation.
• Engage with the MCP community forums.

🤝 Community Contributions

We welcome feature submissions and bug fixes via Pull Requests.

1. Fork the primary repository.
2. Isolate work in a dedicated branch (e.g., git checkout -b feature/enhanced-querying).
3. Commit relevant changes (git commit -m 'feat: Added advanced filter syntax support').
4. Push the branch to your fork.
5. Submit a formal Pull Request for review.

📄 Licensing Information

This software is distributed under the terms of the MIT License (refer to the accompanying LICENSE file).