Notion API

A Python-based MCP for use in exposing Notion functionality to LLMs (Claude)

python

27

GitHub Stars

python

Language

4 months ago

First Indexed

3 weeks ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "pbohannon-notion-api-mcp": {
      "command": "python",
      "args": [
        "-m",
        "notion_api_mcp"
      ],
      "env": {
        "NOTION_API_KEY": "ntn_your_integration_token_here",
        "NOTION_DATABASE_ID": "your_database_id_here",
        "NOTION_PARENT_PAGE_ID": "your_page_id_here"
      }
    }
  }
}

You run a Python-based MCP server that lets AI models interact with Notion to manage todos, databases, and content. This server provides practical, real-time capabilities to create and update tasks, structure content, and work with Notion pages and databases through clean async operations.

How to use

Start the MCP server in your development or integration environment, then connect your MCP client to the local process. You will run the server as a stdio MCP endpoint, and you can configure parameters to point to your Notion workspace.

How to install

Prerequisites you need before installation:

Python 3.8+ should be installed on your system.
A virtual environment tool (uv venv) is used to create an isolated Python environment.
A Notion integration with API access is required for credentials.

Step-by-step commands to install and run the MCP server:

# Clone or download the project directory
# Navigate into the project directory
cd notion-api-mcp

# Create and activate a virtual environment
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies in editable mode
uv pip install -e .

# Prepare environment configuration
cp .env.integration.template .env

# Edit .env to include your Notion credentials and IDs
# NOTION_API_KEY=ntn_your_integration_token_here
# NOTION_PARENT_PAGE_ID=your_page_id_here  (for creating new databases)
# NOTION_DATABASE_ID=your_database_id_here  (for working with existing databases)

# Run the MCP server
python -m notion_api_mcp

Additional sections

Configuration and usage details help you tailor the server to your Notion workspace and workflows.

Environment and connection options include environment variables and multiple ways to run the server. You can use a local .env file for development or set variables directly in your environment.

Available tools

todo_create

Create a new todo item with text, due date, priority, and optional nested subtasks.

todo_update

Update an existing todo item, including status, due date, and text content.

database_create

Create a new Notion database with custom properties, filters, and views.

database_update

Modify properties, filters, or views of an existing Notion database.

content_format

Format and structure content with Markdown, hierarchical lists, and Notion blocks.

real_time_sync

Interact with Notion workspace elements in real time through async operations.