Notion MCP

🚀 Notion MCP Client

A Model Context Protocol (MCP) client for interacting with the Notion API. This client is designed for use in modern AI tools (such as Claude) and supports MCP extended functionality.

🚀 Quick Start

The Notion MCP Client is a powerful tool that allows you to interact with the Notion API efficiently. It provides various features and flexible usage methods to meet different needs.

✨ Features

• Asynchronous API operations with retry logic.
• Concurrency control to respect Notion API rate limits.
• Environment-based configuration.
• JSON-based operation configuration.
• Flexible server implementation with MCP support.
• Fallback to standard HTTP API when MCP is unavailable.

📦 Installation

You can install the notion-mcp package using pip:

pip install notion-mcp

Or install from the source code:

git clone https://github.com/yourusername/notion-mcp.git
cd notion-mcp
pip install -e .

For an additional installation with MCP support:

pip install notion-mcp[mcp]

💻 Usage Examples

Configuration

Create a .env file containing your Notion API credentials and configurations:

NOTION_TOKEN=your_notion_token_here
ROOT_PAGE_ID=your_root_page_id_here
MAX_RETRIES=3
RETRY_DELAYS=1,3,5
CONCURRENCY_LIMIT=5
TIMEOUT_MS=30000

Command Line

Run with default configuration:

notion-mcp

Run with a custom JSON configuration file:

notion-mcp config.json

Server

Start the server (try to use MCP if available):

notion-mcp-server --host 0.0.0.0 --port 8000

The server will attempt to use the MCP protocol. If unavailable, it will fall back to a standard HTTP server, accepting POST requests at /notion.

HTTP API

When using the HTTP API, send a POST request to /notion with a JSON body:

{
  "root_page_id": "your_page_id_here",
  "database_filter": ["Articles", "Resources"],
  "operation": {
    "type": "fill_web_url",
    "params": {
      "web_field": "网址"
    }
  }
}

Example using curl:

curl -X POST http://localhost:8000/notion \
  -H "Content-Type: application/json" \
  -d '{"root_page_id": "your_page_id_here", "operation": {"type": "fill_web_url"}}'

JSON Configuration

Create a JSON configuration file to customize the behavior:

{
  "root_page_id": "your_page_id_here",
  "database_filter": ["Articles", "Resources"],
  "operation": {
    "type": "fill_web_url",
    "params": {
      "web_field": "网址"
    }
  }
}

Using with Claude

To use this MCP client with Claude, you need to set up the server and then configure Claude to use it. Here is an example:

{
  "mcp_configurations": [
    {
      "name": "notion",
      "endpoint": "http://localhost:8000/notion",
      "description": "Access and operate Notion data"
    }
  ]
}

📚 Documentation

To contribute to or extend this project, please clone the repository and refer to the CONTRIBUTING.md file.

This document introduces how to install, configure, and use the Notion MCP Client, as well as how to integrate it with modern AI tools (such as Claude). We hope it helps!