Notion MCP Server: AI-Powered Notion Integration

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

🌟 Key Features

• 📝 Notion Integration: Interact with Notion databases, pages, and blocks.
• 🔌 Universal MCP Compatibility: Works with all MCP clients, including Cursor, Claude Desktop, Cline, and Zed.
• 🔍 Data Retrieval: Fetch information from Notion pages, blocks, and databases.
• ✏️ Content Creation: Create and update Notion pages and blocks.
• 📊 Database Operations: Create, query, and update databases.
• 🔄 Batch Operations: Perform multiple operations in a single request.
• 🗑️ Archive & Restore: Archive and restore Notion pages.
• 🔎 Search Functionality: Search Notion pages and databases by title.

🚀 Getting Started

Setup Process

1. Obtain a Notion API Key:
2. Create an integration at Notion Developers.

3. Copy your API key.

4. Enable Integration for Your Pages:

5. Select a page in Notion.

6. Click the "..." menu → "Connections" → Enable your integration.

7. Choose Your Integration Method:

8. Follow the integration options below based on your preferred MCP client.

9. Interact with Notion:

10. Use commands like:
    • "Create a new page with today's tasks."
    • "Update my meeting notes in Notion."
    • "Add bullet points to my meeting notes page."

🔧 Integration Methods

Cursor Integration

Method 1: Using mcp.json

1. Create or edit .cursor/mcp.json:
   json { "mcpServers": { "notion-mcp-server": { "command": "env NOTION_TOKEN=YOUR_KEY NOTION_PAGE_ID=YOUR_PAGE_ID npx", "args": ["-y", "notion-mcp-server"] } } }
2. Replace YOUR_KEY and YOUR_PAGE_ID with your Notion API key and page ID.

Method 2: Manual Mode

1. Open Cursor → Settings → MCP → Add Server.
2. Enter:
   env NOTION_TOKEN=YOUR_KEY NOTION_PAGE_ID=YOUR_PAGE_ID npx -y notion-mcp-server

Claude Desktop Integration

1. Create or edit mcp.json:
   json { "mcpServers": { "notion-mcp-server": { "command": "npx", "args": ["-y", "notion-mcp-server"], "env": { "NOTION_TOKEN": "YOUR_KEY", "NOTION_PAGE_ID": "YOUR_PAGE_ID" } } } }

🛠 Available Tools

Page Operations

• create_page: Create a new page.
• update_page_properties: Update page properties.
• archive_page: Archive a page.
• restore_page: Restore an archived page.
• search_pages: Search pages by title.

Database Operations

• create_database: Create a new database.
• query_database: Query a database.
• update_database: Update database properties.

Block Operations

• retrieve_block: Retrieve a block.
• retrieve_block_children: Retrieve block children.
• append_block_children: Append child blocks.
• update_block: Update a block.
• delete_block: Delete a block.

Batch Operations

• batch_append_block_children: Append children to multiple blocks.
• batch_update_blocks: Update multiple blocks.
• batch_delete_blocks: Delete multiple blocks.
• batch_mixed_operations: Perform mixed operations in a single request.

🛠 Development

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

❓ Troubleshooting

• Authentication Errors: Ensure your Notion token has the correct permissions.
• Page Access Issues: Verify your integration is added to the pages you're accessing.
• Rate Limiting: Use batch operations to optimize requests.

🤝 Contributing

Contributions are welcome! Submit a Pull Request:
1. Fork the repository.
2. Create your feature branch (git checkout -b feature/amazing-feature).
3. Commit your changes (git commit -m 'Add some amazing feature').
4. Push to the 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.