TODO Helper - MCP Server

A lightweight HTTP Server built with FastAPI to manage todo items in a Notion database. It supports creating, listing, and marking tasks as complete, and distinguishes tasks by user.

Features

• Uses Notion Database as a backend
• Supports user-specific filtering via user_id
• Allows date-based filtering (when) and task completion tracking (completed)
• Automatically ensures required Notion properties exist
• Ready for integration into cross-platform todo applications

Requirements

• Python 3.9+
• FastAPI
• httpx
• python-dotenv
• uvicorn
• pydantic

Install dependencies:

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

Notion Setup

1. Create a Notion integration:

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

2. Share your database with the integration:

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

Environment Setup

Create a .env file in the project root with the following content:

NOTION_API_KEY=your_secret_notion_token
NOTION_DATABASE_ID=your_database_id

Run the Server

python server.py

By default, it runs at http://0.0.0.0:8080

---

API Endpoints

Health Check

GET /

Returns basic status and version information.

---

Get Notion Database Structure

GET /database/info

Returns property definitions and verifies required fields exist.

---

Get All Todos for a User

POST /todos/all
Content-Type: application/json

{
  "user_id": "your-user-id"
}

Returns a list of all todo items for the user.

---

Get Today’s Todos for a User

POST /todos/today
Content-Type: application/json

{
  "user_id": "your-user-id"
}

Returns todos with when set to today.

---

Create a New Todo

POST /todos
Content-Type: application/json

{
  "task": "Buy groceries",
  "when": "2025-01-15",  // optional, can be empty string
  "user_id": "your-user-id"
}

Returns the created task ID.

---

Mark a Todo as Completed

PUT /todos/{task_id}/complete

Marks the given task as complete.

---

Notion Database Requirements

The following properties are required in your Notion database. The service will auto-create them if they are missing:

• Task (type: title)
• Completed (type: checkbox)
• When (type: date)
• User (type: rich_text)

---

Tips

• The when field should follow YYYY-MM-DD format (e.g., "2025-01-15").
• The todo task is stored as a JSON string in the Notion title to preserve structured data.
• For production deployment, use a production server (e.g. Gunicorn + Uvicorn workers).

---

License

MIT License

---

Acknowledgments

• https://github.com/danhilse/notion_mcp