home / mcp / notion mcp server

Notion MCP Server

Provides an MCP interface to manage a Notion-based todo list via add, show, and complete actions.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "ruijian-zha-notion_mcp_advanced": {
      "command": "/path/to/your/.venv/bin/python",
      "args": [
        "-m",
        "notion_mcp"
      ],
      "env": {
        "NOTION_API_KEY": "YOUR_API_KEY_PLACEHOLDER",
        "NOTION_DATABASE_ID": "YOUR_DATABASE_ID_PLACEHOLDER"
      }
    }
  }
}

This MCP server lets you manage a Notion-based todo list through an MCP client. It runs a small command‑line interface that communicates with Notion via your integration’s API key, letting you add, view, and mark tasks as complete from any MCP-enabled client or Claude Desktop.

How to use

You interact with the Notion MCP server through an MCP client or Claude Desktop. Use the following practical actions to manage your Notion todo list: add new todos with descriptions and links, view all current todos, and check off items as complete. You can compose natural language prompts like “Show all my todos,” “Add a todo: finish design doc with link,” or “Mark todo 3 as complete” and the MCP server will translate them into Notion API calls.

To ensure a smooth experience, keep your Notion API key and database ID ready. You’ll reference them in the configuration so the server can authenticate and locate the correct Notion database.

How to install

Prerequisites you need before installing the MCP server:

- Python 3.10 or higher

- A Notion account

- A Notion integration API key

- A Notion database that matches the expected structure (Task as title, Checkbox for completion, Description, and Link)

Follow these steps to set up the server and its environment exactly as shown:

# 1. Clone the server repository
git clone https://github.com/yourusername/notion-mcp.git
cd notion-mcp

# 2. Create and activate a Python virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows use: .venv\Scripts\activate

# 3. Install the MCP package in editable mode
pip install -e .

Configure your Notion and MCP settings

Create a Notion integration and prepare environment variables for the MCP server. The following configuration is used to run the server via Python from your virtual environment.

NOTION_API_KEY=your-api-key-here
NOTION_DATABASE_ID=your-database-id-here

Configure Claude Desktop for MCP

Configure Claude Desktop to start the server automatically. Create a configuration block that runs the MCP using your virtual environment.

{
  "mcpServers": {
    "notion_todo": {
      "command": "/path/to/your/.venv/bin/python",
      "args": ["-m", "notion_mcp"],
      "cwd": "/path/to/notion-mcp"
    }
  }
}

Available tools

add_todo

Create a new todo item with a title, optional description, and an optional link to an external resource.

list_todos

Retrieve and display all current todos from the Notion database, including completion status and links.

complete_todo

Mark a specific todo item as completed using its identifier.

attach_link

Attach or update a URL or reference for a todo item to provide additional context.