📌Overview

Purpose: This framework aims to provide a simple integration between a personal todo list in Notion and the Model Context Protocol (MCP) for personal task management through Claude.

Overview: The Notion MCP Integration is a lightweight server that enables users to effectively manage their minimalist todo lists within Notion by utilizing its API. It is designed for a specific use case, allowing seamless task management with basic functionalities for adding, viewing, and completing tasks.

Key Features:

• Add New Todo Items: Users can create new tasks and specify their due timing as either "today" or "later."

• View All Todos: Provides functionality to review the entire list of tasks at any time, offering a straightforward way to keep track of responsibilities.

• View Today's Tasks: Enables users to see only the tasks assigned for the current day, helping prioritize daily activities.

• Check Off a Task as Complete: Allows users to mark tasks as completed, providing a simple way to manage task completion and progress tracking.

---

Notion MCP Integration

A simple Model Context Protocol (MCP) server that integrates with Notion's API to manage a minimalist personal todo list through Claude. This is a basic implementation tailored specifically for a simple todo list setup in Notion.

Important Note

This project is designed for a specific use case: a simple Notion todo list with just three properties:

• Task (title)
• When (select with options: "today" or "later")
• Checkbox (marks if completed)

Example Notion Database

While this can serve as a starting point for your own Notion integration, you will likely need to modify the code to match your specific database structure and requirements.

Features

• Add new todo items
• View all todos
• View today's tasks
• Check off a task as complete

Prerequisites

• Python 3.10 or higher
• A Notion account
• A Notion integration (API key)
• A Notion database matching the structure described above (or willingness to modify the code)

Setup

1. Clone the repository:

   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
   uv pip install -e .
   

3. Create a Notion integration:

   • Go to https://www.notion.so/my-integrations
   • Create new integration
   • Copy the API key

4. Share your database with the integration:

   • Open your todo database in Notion
   • Click "..." menu → "Add connections"
   • Select your integration

5. Create a .env file in the project root:

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

6. Configure Claude Desktop:

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

Running the Server

The server can be run in two ways:

1. Directly from the command line:

   # From the project directory with virtual environment activated
   python -m notion_mcp
   

2. Automatically through Claude Desktop (recommended):

   • The server starts automatically when Claude launches if configured correctly
   • No manual server management required
   • Server stops when Claude is closed

Note: When running directly, the server will not show output unless there is an error, which is normal as it waits for MCP commands.

Usage

Basic commands through Claude include:

• Show all my todos
• What's on my list for today?
• Add a todo for today: check emails
• Add a task for later: review project

Limitations

• Works only with the specific Notion database structure described
• No support for complex database schemas
• Limited to "today" or "later" task scheduling
• No support for additional properties or custom fields
• Basic error handling only
• No advanced features like recurring tasks, priorities, or tags

Customization

To use this with a different database structure, modify the server.py file, especially:

• The create_todo() function to match your database properties
• The todo formatting in call_tool() to handle your data structure
• The input schema in list_tools() if you want different options

Project Structure

notion_mcp/
├── pyproject.toml
├── README.md
├── .env                   # Not included in repo
└── src/
    └── notion_mcp/
        ├── __init__.py
        ├── __main__.py
        └── server.py      # Main implementation

License

MIT License - Use at your own risk

Acknowledgments

• Built to work with Claude Desktop
• Utilizes Notion's API