notion mcp

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

Important Note

This is a personal project designed for a very specific use case: my simple Notion todo list that has just three properties: - Task (title) - When (select with only two options: "today" or "later") - Checkbox (marks if completed)

Example Notion Database

While you can use this as a starting point for your own Notion integration, you'll 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 that matches the exact structure described above (or willingness to modify the code for your structure)

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

3. Create a Notion integration:

4. Go to https://www.notion.so/my-integrations
5. Create new integration

6. Copy the API key

7. Share your database with the integration:

8. Open your todo database in Notion
9. Click "..." menu → "Add connections"

10. Select your integration

11. Create a .env file:

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

12. 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):

3. The server will start when Claude launches if configured correctly in claude_desktop_config.json
4. No manual server management needed
5. Server stops when Claude is closed

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

Usage

Basic commands through Claude: - "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

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

Customization

If you want to use this with a different database structure, you'll need to modify the server.py file, particularly: - 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
• Uses Notion's API