Notion MCP Server

🚀 Configuring Notion API Keys and Permissions

This guide offers a detailed walk - through on configuring Notion API keys and permissions, along with code examples and setup instructions in Claude.

✨ Features

• Step - by - step guide to create a Notion API key.
• Instructions for configuring page permissions to use the integration.
• Code updates and examples for using the Notion API.
• Setup guidance in Claude, including installing tools and setting environment variables.
• Installation instructions for the Notion library.
• Examples of generating docstrings for functions.

📦 Installation

Install the Notion Library

Use pip to install the notion - client:

pip install notion - client

💻 Usage Examples

Create a Notion API Key

1. Access Notion Integrations:
   • Visit [Notion Integrations](https://www.notion.so/my - integrations) and log in with your Notion account.
2. Create a New Integration:
   • Click "New Integration", fill in the required fields (e.g., integration name), and select the workspace you want to connect.
3. Save the Integration:
   • After submission, an API key will be generated. Copy and securely save this key for subsequent API request authentication.
4. Retrieve the API Key:
   • Copy the generated API key and ensure its security.

Configure Page Permissions to Use the Integration

1. Open a Notion Page:
   • Open the Notion page to which you want to grant permissions.
2. Share the Page:
   • Click the "Share" button at the top - right of the page.
3. Invite the Integration:
   • Enter your integration name in the "Invite" text box and select it from the dropdown list. This will grant the integration access to the page.
4. Set Permissions:
   • Ensure that the integration has the necessary permissions to perform the required operations (e.g., read, write).

Code Updates

In the notion_sdk.py file, update PAGE_ID to the ID of the page you created earlier. You can obtain this ID by copying the page link.

Example Notion Page ID

https://www.notion.so/MCP - Parent - Page - 1d21f7216bdb80789f88fccd964b5031

Curl Example

The following is an example of using the Notion API to create a new page:

curl --location --request POST 'https://api.notion.com/v1/pages' \
--header 'Authorization: Bearer $NOTION_API_KEY' \
--header 'Content - Type: application/json' \
--header 'Notion - Version: 2021 - 05 - 13' \
--data '{
"parent": { "page_id": "1d21f7216bdb80789f88fccd964b5031" },
"properties": {
    "title": [
        {
            "text": {
                "content": "New Page Title"
            }
        }
    ]
}
'

Setup in Claude

Install the uv Tool

If you are using a Mac, install it via the following command:

brew install uv

Verify the installation:

uv --version

Run a Python script:

uv run <script>.py

Set Environment Variables

In Claude, you need to add NOTION_API_KEY to the environment variables. For example:

export NOTION_API_KEY=your_api_key_here

Alternatively, specify the executable file path in the configuration file:

{
  "executors": {
    "default_python": {
      "command": "/usr/bin/python3",
      "env": {
        "NOTION_API_KEY": "your_api_key"
      }
    }
  }
}

Generate Docstring Examples

The following are examples of docstrings for functions to help LLMs and humans understand the usage and parameters of the tools:

Example Function and Its Docstring

def get_page_content(page_id: str) -> dict:
    """
    Get the content of a specified page.
    
    Args:
        page_id (str): The ID of the page whose content needs to be retrieved.
        
    Returns:
        dict: The page content, including the title and other attributes.
    """
    # Specific implementation code

Another Example

def create_new_page(parent_id: str, title: str) -> str:
    """
    Create a new page under a specified parent page.
    
    Args:
        parent_id (str): The ID of the parent page.
        title (str): The title of the new page.
        
    Returns:
        str: The ID of the newly created page.
    """
    # Specific implementation code

Usage Notes

• Summary: Briefly describe the purpose of the function.
• Parameters: Explain each input parameter, its type, and its purpose in detail.
• Return Value: Clearly define the type and meaning of the return value.

By following these specifications, you can ensure that docstrings are both human - friendly and model - friendly.