Notion MCP

🚀 Simple MCP Server for Personal To-Do List (Notion Integration)

A simple Model Context Protocol (MCP) server that integrates the Notion API to manage my personal to-do list.

🚀 Quick Start

Prerequisites

• Python 3.11 or higher
• A Notion account with API access
• A Notion integration token
• A Notion page where you want to manage your to-do list
• Claude Desktop client

Installation

Install via Smithery

Automatically install Notion MCP using Smithery:

npx -y @smithery/cli install @Badhansen/notion-mcp --client claude

Manual Installation

1. Clone the repository:

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

2. Set up the Python environment:

uv venv
source .venv/bin/activate
uv pip install -e .

3. Create a Notion integration:
   • Visit https://www.notion.so/my-integrations.
   • Create a new integration.
   • Copy the API token.
4. Share your database/page with the integration:
   • Open the database/table or page in your Notion workspace.
   • Click "..." in the menu.
   • Go to "Add connections".
   • Select your integration (search by name).

Configuration

1. Create a .env file:

cp .env.example .env

2. Configure your Notion credentials in the .env file:

NOTION_TOKEN=<Your Notion API Token>
PAGE_ID=<Your Notion Page ID>
NOTION_VERSION="2022-06-28"
NOTION_BASE_URL="https://api.notion.com/v1"

3. To use with Claude Desktop, adjust your claude_desktop_config.json file. Go to Claude Desktop -> Settings -> Developers -> Profile and edit:

{
  "mcpServers": {
    "notionMcp": {
      "url": "http://localhost:5000",
      "enabled": true
    }
  }
}

✨ Features

• Display Tasks: List all to-do items.
• Add Tasks: Create new to-do items.
• Update Task Status: Mark tasks as completed.

💻 Usage Examples

Basic Usage

Display all tasks

{
  "command": "listTasks"
}

Add a new task

{
  "command": "addTask",
  "task": "Buy groceries"
}

Mark a task as completed

{
  "command": "completeTask",
  "taskId": "unique_task_id_123"
}

📚 Documentation

Demo

Visual Guide

Notion MCP Query 1

Notion MCP Query 2

Notion MCP Query 3

Project Structure

notion-mcp/
├── server.py          # Main server file
├── config.py         # Configuration parameters
├── routes/           # Route definitions
│   ├── tasks.py      # Routes related to to-do items
├── utils/            # Utility functions
│   ├── notion_utils.py  # Notion API utilities
└── README.md         # Project documentation

Contribution Guidelines

1. Fork the repository: Fork this project on GitHub.
2. Create a branch: Create a new branch for new features or bug fixes.
3. Commit changes: Commit your modifications with detailed descriptions.
4. Push to the remote repository.
5. Open a Pull Request: Submit a pull request against the main branch.

📄 License

This project is licensed under the MIT License.