home / mcp / notion mcp integration mcp server

Notion MCP Integration MCP Server

Provides a Python-based MCP server to manage a Notion todo list via Claude, enabling add, view, and complete tasks.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "danhilse-notion_mcp": {
      "command": "python",
      "args": [
        "-m",
        "notion_mcp"
      ],
      "env": {
        "NOTION_API_KEY": "YOUR_API_KEY",
        "NOTION_DATABASE_ID": "YOUR_DATABASE_ID"
      }
    }
  }
}

This MCP server lets you manage a Notion-based todo list through Claude by exposing a simple set of commands to add, view, and complete tasks. It runs as a Python module and integrates with your Notion database to keep your tasks synchronized and actionable from Claude.

How to use

You interact with the Notion MCP server through Claude by issuing natural language commands that map to todo actions. You can view all tasks, see today’s tasks, add a new task for today or for later, and mark tasks as completed. Start the server first, then configure Claude to connect to it if you want Claude to drive your workflow.

How to install

Prerequisites you need before you begin:

Python 3.10 or higher
A Notion account
A Notion integration with an API key
A Notion database that matches the described structure (Task, When with today/later, Checkbox)

Follow these concrete steps to set up locally:

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

# 2. Set up Python environment
python -m venv .venv
source .venv/bin/activate  # On Windows use: .venv\Scripts\activate
pip install -e .

3. Create a Notion integration and obtain the API key from your Notion account. Then share your database with the integration so the MCP can access the data.

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

4. Configure Claude Desktop to connect to your MCP server as shown in the example configuration snippet below (these fields must be adjusted to your environment).

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

Additional setup notes

Create a local environment file with your Notion credentials as shown above. You can customize the Notion database structure in the source if your setup differs. The server runs in the background and will accept MCP commands from Claude once started.

Usage notes

Run the server directly to keep it running in your shell or allow Claude Desktop to manage it automatically. When running directly, no output appears unless an error occurs — this is expected while the server waits for MCP commands.

Security and reliability considerations

Keep your API key secure and do not commit it to version control. Use a dedicated Notion integration with limited permissions if possible, and rotate keys as needed. Ensure the Notion database structure matches the expected fields to prevent misalignment between Claude commands and Notion records.

Examples of common tasks

Add a new todo for today: create a task labeled accordingly, e.g., Add a todo for today: check emails.

View today’s tasks: ask Claude to show tasks scheduled for today.

Mark a task as completed: find the task in the Notion database and check its Checkbox property.

Notes on customization

If you want to adapt this MCP to a different Notion database structure, modify the functions that create todos and format the responses to match your properties and constraints.

Available tools

show_todos

Retrieve and display all tasks from the Notion Todo database and present them to the user.

list_today

Filter and show tasks that are marked for today in the Notion database.

add_todo_today

Create a new todo item with the When set to today and the provided task description.

add_todo_later

Create a new todo item with the When set to later and the provided task description.

complete_todo

Mark the selected task as completed by toggling its Checkbox property in Notion.