TaskPad

A Windows system-tray task manager and reminder engine with deep AI and automation integration.

• System tray icon — colour-coded badge (blue / green / amber / red) with a task count

• Floating overlay — always-on-top compact task list; drag it anywhere on screen

• Reminder engine — fires desktop alerts and system sounds at the scheduled time

• MCP server — Claude Code, Claude Desktop, and claude.ai can all read and write your tasks

• REST API — JSON API on localhost:8765 for n8n, Home Assistant, or any HTTP client

• Outbound webhooks — push task.created, task.completed, reminder.fired, etc. to any URL

Table of contents

1. Requirements

2. Installation

3. Running from source

4. Tray icon guide

5. Cloudflare tunnel setup

6. Claude Desktop setup

7. Claude Code setup

8. claude.ai browser setup

9. n8n integration

10. REST API reference

11. Outbound webhook events

12. Configuration file

13. Building the installer

Related MCP server: Procrastinator MCP Server

Requirements

TaskPad stores its data in %APPDATA%\TaskPad\ (i.e. C:\Users\<you>\AppData\Roaming\TaskPad\).

Installation

Run the installer — TaskPad-Setup-1.0.0.exe — and follow the wizard.

The wizard will:

1. Copy all source files to C:\Program Files\TaskPad\ (or your chosen path).

2. Optionally add a desktop shortcut and a Windows autostart entry.

3. Run pip install -r requirements.txt with the detected Python interpreter.

4. Ask for an optional Cloudflare tunnel URL (for Claude AI) and n8n webhook URL — you can skip these and configure them later from the tray menu.

After the installer completes, tick "Launch TaskPad now" on the final page or start it from the Start menu / desktop shortcut.

Note: If Python was not detected, install it from python.org/downloads, then open a terminal in the install folder and run:

pip install -r requirements.txt

Running from source

# Clone / copy the source, then:
pip install -r requirements.txt
python main.py

MCP stdio mode (for Claude Code / Claude Desktop):

python main.py --mcp

Tray icon guide

The tray icon colour tells you your task state at a glance:

A number badge in the top-right corner shows the count of incomplete tasks (up to 99).

Right-click menu:

Cloudflare tunnel setup

TaskPad exposes the MCP server on port 8766 (HTTP/SSE). To make it reachable from claude.ai or n8n on another machine you need to expose that port via a Cloudflare tunnel.

Option A — Permanent named tunnel (recommended)

This gives you a stable URL that survives restarts.

1. Create the tunnel in the Cloudflare dashboard:

   • Cloudflare Zero Trust → Access → Tunnels → Create a tunnel

   • Name it (e.g. taskpad).

   • Under Public hostname, add a subdomain pointing to http://localhost:8766 e.g. taskpad.yourdomain.com

   • Install / authenticate cloudflared on this machine (the dashboard shows the command).

2. Tell TaskPad the stable URL:

   • Right-click tray icon → MCP Settings…

   • Enter https://taskpad.yourdomain.com and save.

   • TaskPad will use this URL immediately (no cloudflared management needed — you run cloudflared separately as a service).

3. Expose the REST API too (for n8n on another server):

   • Add a second public hostname in the same tunnel: taskpad-api.yourdomain.com → http://localhost:8765

   • Use this URL as the base URL in n8n.

Option B — Quick ephemeral tunnel (development / testing)

If cloudflared is on your PATH or in %APPDATA%\TaskPad\cloudflared.exe, TaskPad will start a quick tunnel automatically on launch and show a tray notification with the URL. The URL changes every restart.

TaskPad will download cloudflared.exe automatically from GitHub if it is not found.

Claude Desktop setup

1. Open Claude Desktop → Settings → Developer → Edit Config (claude_desktop_config.json).

2. Add under "mcpServers":

{
  "mcpServers": {
    "taskpad": {
      "command": "python",
      "args": ["C:\\Program Files\\TaskPad\\main.py", "--mcp"]
    }
  }
}

3. Restart Claude Desktop. TaskPad should appear in the tool list.

Use pythonw instead of python if you want to suppress the console window.

Claude Code setup

Run once in a terminal:

claude mcp add taskpad -s user -- python "C:\Program Files\TaskPad\main.py" --mcp

Verify it is registered:

claude mcp list

Claude Code will now have access to all TaskPad tools in every project.

claude.ai browser setup

claude.ai connects over HTTP/SSE (not stdio), so it needs the tunnel URL.

1. Complete the Cloudflare tunnel setup to get a stable public URL.

2. In claude.ai → Settings → Integrations → Add MCP server:

   • URL: https://taskpad.yourdomain.com/sse

3. Save. The TaskPad tools will appear in your claude.ai conversations.

n8n integration

TaskPad acts as both an inbound HTTP server (n8n calls it) and an outbound webhook sender (TaskPad calls n8n).

Inbound — n8n creates tasks in TaskPad

Use an HTTP Request node in n8n:

Example body (email flagged → task with link back):

{
  "title": "Follow up on invoice from Acme",
  "category": "work",
  "priority": "high",
  "remind_at": "2026-08-01T09:00:00",
  "notes": "Flagged in Outlook — needs reply by EOD",
  "source_url": "https://outlook.office.com/mail/deeplink/..."
}

Find your API key: right-click tray → Integration Settings… → copy the key shown.

Outbound — TaskPad notifies n8n

1. In n8n, create a Webhook node. Copy its URL.

2. In TaskPad: right-click tray → Integration Settings… → paste the URL in n8n webhook URL and save.

TaskPad will POST a JSON payload to that URL for each enabled event.

REST API reference

Base URL (local): http://127.0.0.1:8765 Base URL (remote): https://taskpad-api.yourdomain.com

All endpoints except /health require the header:

X-API-Key: <your-api-key>

Interactive docs are available at http://127.0.0.1:8765/docs while TaskPad is running.

Endpoints

Task schema

{
  "title":               "string (required)",
  "category":            "work | personal | shared",
  "task_type":           "todo | reminder | both",
  "priority":            "urgent | high | normal | none",
  "notes":               "string",
  "tags":                ["string"],
  "due_date":            "YYYY-MM-DD or null",
  "remind_at":           "ISO datetime or null",
  "repeat":              "none | daily | weekdays | weekly | monthly | every_n_days",
  "repeat_n":            1,
  "repeat_days":         [0,1,2,3,4],
  "repeat_day_of_month": 1,
  "enabled":             true,
  "source_url":          "https://... or null"
}

Example — create a task with curl

curl -X POST https://taskpad-api.yourdomain.com/tasks \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Review PR #42",
    "category": "work",
    "priority": "high",
    "remind_at": "2026-08-01T10:00:00",
    "source_url": "https://github.com/your-org/your-repo/pull/42"
  }'

Outbound webhook events

When a webhook URL is configured, TaskPad POSTs a JSON body to it for each event.

Payload shape:

{
  "event":      "task.created",
  "task_id":    "abc123",
  "title":      "Review PR #42",
  "category":   "work",
  "priority":   "high",
  "task_type":  "todo",
  "remind_at":  "2026-08-01T10:00:00",
  "due_date":   null,
  "completed":  false,
  "source_url": "https://github.com/...",
  "created_at": "2026-07-28T08:00:00",
  "updated_at": "2026-07-28T08:00:00"
}

Configuration file

%APPDATA%\TaskPad\config.json — created automatically on first run.

{
  "api_key":       "auto-generated 48-char hex key",
  "mcp_public_url": "https://taskpad.yourdomain.com",
  "webhook_url":   "https://n8n.yourdomain.com/webhook/taskpad",
  "webhook_events": [
    "task.created", "task.completed", "reminder.fired", "task.overdue"
  ],
  "sound_type":    "system",
  "system_sound":  "SystemExclamation"
}

All settings are editable from the tray menu — direct JSON editing is not normally required.

Releasing a new version

release.ps1 handles the full release cycle in one command:

.\release.ps1              # bump patch (1.0.0 → 1.0.1), build, commit, tag, push
.\release.ps1 -Bump minor  # bump minor (1.0.0 → 1.1.0)
.\release.ps1 -Bump major  # bump major (1.0.0 → 2.0.0)
.\release.ps1 -Version 1.5.0  # explicit version
.\release.ps1 -NoBuild     # commit + tag only, skip installer build
.\release.ps1 -NoPush      # build + tag locally, do not push to remote

What it does, in order:

1. Reads the current version from version.py

2. Calculates the new version (or uses -Version)

3. Asks for confirmation before doing anything

4. Writes the new version back to version.py

5. Builds the installer via build.ps1 (unless -NoBuild)

6. git commit — chore: release v1.0.1

7. git tag -a v1.0.1

8. git push + git push --tags (unless -NoPush or no remote)

If the project has not been initialised as a git repo yet, the script will run git init and do an initial commit automatically.

Building the installer

Prerequisites:

• Python 3.10+ with Pillow (pip install Pillow)

• Inno Setup 6 installed

To release a new version, edit version.py:

__version__ = "1.1.0"

Then run from the project root:

.\build.ps1

Or override the version without editing the file:

.\build.ps1 -Version 1.1.0

The build script will:

1. Read version.py (or use -Version override).

2. Generate assets/icon.ico (all sizes from 16 to 256 px).

3. Compile installer/taskpad.iss with ISCC, injecting the version.

4. Output installer/output/TaskPad-Setup-<version>.exe.

The version string also appears in the tray icon tooltip (TaskPad v1.1.0).

File layout

TaskPad/
├── main.py               # Entry point — tray app or --mcp mode
├── models.py             # Task dataclass
├── store.py              # SQLite storage + config helpers
├── scheduler.py          # Reminder / overdue scheduler
├── requirements.txt
├── LICENSE.txt
├── build.ps1             # Build script (icon + Inno Setup)
├── api/
│   ├── server.py         # FastAPI REST server on :8765
│   └── webhooks.py       # Outbound webhook sender
├── mcp_server/
│   ├── server.py         # MCP stdio server (--mcp flag)
│   ├── http_server.py    # MCP HTTP/SSE server on :8766
│   └── tunnel.py         # Cloudflare tunnel manager
├── ui/
│   ├── overlay.py        # Floating task overlay
│   ├── alert.py          # Reminder alert dialog
│   └── widgets.py        # Custom PIL-based widgets
├── assets/
│   └── icon.ico          # Generated by build.ps1
└── installer/
    ├── taskpad.iss        # Inno Setup script
    ├── launcher.vbs       # No-console launcher (wscript.exe)
    ├── generate_icon.py   # PIL icon generator
    └── write_config.py    # Post-install config writer

License

MIT — see LICENSE.txt.