MCP HubMCP Hub
awkoy

notion-mcp-server

by: awkoy

**Notion MCP Server** is a Model Context Protocol (MCP) server implementation that enables AI assistants to interact with Notion's API. This production-ready server provides a complete set of tools.

92created 18/03/2025
Visit
Notion
API

📌Overview

Purpose: The Notion MCP Server aims to facilitate interactions between AI assistants and Notion's API, allowing users to manage Notion content via natural language.

Overview: This production-ready server is designed to help developers integrate AI functionalities with Notion, offering a robust set of tools and endpoints for manipulating Notion's data structure efficiently.

Key Features:

  • 📝 Notion Integration: Allows seamless interaction with Notion databases, pages, and blocks to enhance content management.

  • 🔌 Universal MCP Compatibility: Supports various MCP clients including Cursor, Claude Desktop, and others, ensuring versatility.

  • 🔍 Data Retrieval: Users can fetch information from Notion, enabling their AI assistants to access and utilize relevant data.

  • ✏️ Content Creation: Enables users to create and update pages and blocks within Notion using just their voice or text commands.

  • 📊 Block Management: Provides features to append, update, and delete blocks within Notion pages, streamlining content organization.

  • 💾 Database Operations: Facilitates the creation, querying, and updating of databases for efficient project tracking.

  • 🔄 Batch Operations: Empowers users to perform multiple operations in a single request, optimizing interaction efficiency.

  • 🗑️ Archive & Restore: Allows users to archive and restore pages as needed, enhancing data management capabilities.

  • 🔎 Search Functionality: Supports searching for pages and databases by title, making information retrieval quick and user-friendly.

Notion MCP Server

Notion MCP Server is a Model Context Protocol (MCP) server implementation that enables AI assistants to interact with Notion's API. This production-ready server provides tools and endpoints for reading, creating, and modifying Notion content through natural language interactions.

🚧 Active Development: Database support is now available! Comments and user management tools have been added. If you find this project useful, please consider giving it a star to support further development.

📑 Table of Contents

  • Getting Started & Integration
    • Setup Process
    • Cursor Integration
    • Claude Desktop Integration
  • Features
  • Documentation
    • Available Tools
    • Available Resources
  • Development
  • Technical Details
  • Troubleshooting
  • Contributing
  • License

🚀 Getting Started & Integration

Setup Process

  1. Obtain a Notion API Key

  2. Enable Integration for Your Pages

    • Select or create a page in Notion
    • Click the "..." menu in the top right corner
    • Go to "Connections"
    • Find and enable your integration from the list

  3. Choose Your Integration Method

    • Follow one of the integration options below based on your preferred MCP client

  4. Ask Your AI Assistant to Interact with Notion

    • Example commands:
      • "Create a new page with today's tasks"
      • "Update my meeting notes in Notion"
      • "Add bullet points to my meeting notes page"
      • "Create a new database for tracking projects"
      • "Add new entries to my task database"
      • "Add a comment to my project page"
      • "Show me all comments on this document"
      • "List all users in my workspace"
      • "Get information about a specific user"

Cursor Integration

Method 1: Using mcp.json

  1. Create or edit the .cursor/mcp.json file in your project directory:
{
  "mcpServers": {
    "notion-mcp-server": {
      "command": "env NOTION_TOKEN=YOUR_KEY NOTION_PAGE_ID=YOUR_PAGE_ID npx",
      "args": ["-y", "notion-mcp-server"]
    }
  }
}
  1. Replace YOUR_KEY and YOUR_PAGE_ID with your actual Notion API key and page ID
  2. Restart Cursor to apply the changes

Method 2: Manual Mode

  1. Open Cursor settings
  2. In the "MCP" or "Model Context Protocol" section, add a new server
  3. Enter the following command:
env NOTION_TOKEN=YOUR_KEY NOTION_PAGE_ID=YOUR_PAGE_ID npx -y notion-mcp-server
  1. Replace YOUR_KEY and YOUR_PAGE_ID accordingly
  2. Save and restart Cursor if necessary

Claude Desktop Integration

  1. Create or edit the mcp.json file in your configuration directory:
{
  "mcpServers": {
    "notion-mcp-server": {
      "command": "npx",
      "args": ["-y", "notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "YOUR_KEY",
        "NOTION_PAGE_ID": "YOUR_PAGE_ID"
      }
    }
  }
}
  1. Replace YOUR_KEY and YOUR_PAGE_ID with actual values
  2. Restart Claude Desktop to apply changes

🌟 Features

  • Notion Integration: interact with databases, pages, and blocks
  • Universal MCP Compatibility: supports Cursor, Claude Desktop, Cline, and Zed
  • Data Retrieval: fetch data from pages, blocks, and databases
  • Content Creation: create and update pages and blocks
  • Block Management: append, update, delete blocks
  • Database Operations: create, query, update databases
  • Batch Operations: multiple operations in a single request
  • Archive & Restore functionality for pages
  • Search by title in pages and databases
  • Comments Management: get, create, reply to comments
  • User Management: retrieve workspace users and user details

📚 Documentation

Available Tools

notion_pages

Operations include creating pages, updating properties, archiving/restoring pages, searching by title.

Example:

{
  "payload": {
    "action": "create_page", 
    "params": {
      // parameters for action
    }
  }
}

notion_blocks

Manage blocks: retrieve content and children, append, update, delete blocks, batch operations.

Example:

{
  "payload": {
    "action": "append_block_children",
    "params": {
      // parameters
    }
  }
}

notion_database

Create, query, and update databases.

Example:

{
  "payload": {
    "action": "create_database",
    "params": {
      // parameters
    }
  }
}

notion_comments

Manage comments: get comments, add page comments, reply to discussions.

Example:

{
  "payload": {
    "action": "get_comments",
    "params": {
      // parameters
    }
  }
}

notion_users

Access user information: list users, get user details, bot info.

Example:

{
  "payload": {
    "action": "list_users",
    "params": {
      // parameters
    }
  }
}

Available Resources

The server currently focuses on tool-based operations and does not expose additional resources.

🛠 Development

  1. Clone the repository:
git clone https://github.com/awkoy/notion-mcp-server.git
cd notion-mcp-server
  1. Install dependencies:
npm install
  1. Set environment variables in .env:
NOTION_TOKEN=your_notion_api_key
NOTION_PAGE_ID=your_notion_page_id
  1. Build project:
npm run build
  1. Run inspector:
npm run inspector

🔧 Technical Details

  • Built with TypeScript and MCP SDK v1.7.0+
  • Uses official Notion API client (@notionhq/client v2.3.0+)
  • Implements Model Context Protocol specification
  • Tools support CRUD operations on pages, blocks, databases
  • Supports batch operations for efficiency
  • Input/output validated using Zod schemas

❓ Troubleshooting

  • Authentication Errors: Verify Notion token permissions and integration enabled on pages/databases

  • Page Access Issues: Ensure integration is added to accessed pages

  • Rate Limiting: Use batch requests to optimize Notion API calls

  • For help:

🤝 Contributing

Contributions are welcome:

  1. Fork the repo
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Commit your changes: git commit -m 'Add some amazing feature'
  4. Push branch: git push origin feature/amazing-feature
  5. Open a Pull Request

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.