Notion MCP

🚀 MCP Server Integrated with Notion

A simple Model Context Protocol (MCP) server that integrates Notion's API to manage personal to-do lists via Claude. This implementation is tailored for my minimalist to-do list.

🚀 Quick Start

This is a straightforward guide to get the MCP server up and running.

✨ Features

• Add new to-do items.
• View all to-do items.
• View today's work tasks.
• Mark tasks as completed.

📦 Installation

Prerequisites

• Python 3.10 or higher.
• A Notion account.
• A Notion API key.
• A Notion database that matches the above description (or the willingness to modify according to your own structure).

Steps

1. Clone the repository:

git clone https://github.com/yourusername/notion-mcp.git
cd notion-mcp

2. Set up the Python environment:

python -m venv .venv
source .venv/bin/activate  # On Windows, use: .venv\Scripts\activate
pip install -e .

3. Create a Notion integration:

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

4. Share the integration with your database:

   • Open your to-do database.
   • Click "..." in the menu → "Add connection".
   • Select your integration.

5. Create a .env file:

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"
    }
  }
}

💻 Usage Examples

Basic Usage

The server can be run in two ways:

1. Directly from the command line:

# In the project directory, after activating the virtual environment
python -m notion_mcp

2. Automatically via Claude Desktop (recommended):

• If correctly configured in claude_desktop_config.json, the server will run automatically when Claude starts.
• No manual server management is required.
• The server will stop when Claude is closed.

Note: When running directly, the server will not display any output unless there is an error - this is normal as it is waiting for MCP commands.

Using with Claude

Use basic commands in Claude:

• "Show me all my to-do items."
• "What's on my list today?"
• "Add a to-do item for today: Check emails."
• "Add a task for later: Review the project."

📚 Documentation

Limitations

• Can only be used with a specific Notion database structure.
• Does not support complex database architectures.
• Limited to task scheduling for "today" or "later".
• Does not support other attributes or custom fields.
• Basic error handling.
• No advanced features such as recurring tasks, priorities, or tags.

Customization

If you want to use a different database structure, modify the server.py file, especially:

• The create_todo() function to match your database attributes.
• The task formatting in call_tool() to handle your data structure.
• The input patterns in list_tools() if you want different options.

Project Structure

notion_mcp/
├── pyproject.toml
├── README.md
├── .env                   # Not included in the repository
└── src/
    └── notion_mcp/
        ├── __init__.py
        ├── __main__.py
        └── server.py      # The main implementation file

📄 License

[Insert license information here, e.g., MIT License or other applicable licenses]

Contributors

[List the names or GitHub usernames of contributors]

📋 Additional Notes

[If any, add other notes such as issue reporting, support, etc.]

⚠️ Important Note

This project is designed for specific needs. If you have other requirements, please adjust it according to your specific situation.

⚠️ Another Important Note

This is a personal project designed for a specific use case: my simple Notion to-do list, which has only three attributes:

• Task (title)
• Time (selector with only two options: "today" or "later")
• Checkbox (to mark completion)

Example Notion Database

Although you can use this code as a starting point for your own Notion integration, you may need to modify it according to your database structure and requirements.