whenful-mcp 0.5.1

Local MCP server for Whenful — encrypted task access via Claude Desktop and other MCP clients.

whenful-mcp

Local Model Context Protocol (MCP) server for Whenful. Connects Claude Desktop, Codex, and other MCP-compatible AI clients to your Whenful tasks — including for accounts with end-to-end encryption enabled.

Why this exists

Whenful's cloud MCP at whenful.com/mcp works for accounts without encryption. For encrypted accounts, the server has no key by architectural design — so cloud MCP can't decrypt. whenful-mcp runs locally, holds the encryption key in memory after passphrase unlock, decrypts client-side, and serves plaintext to your MCP client. The privacy promise stays intact and MCP keeps working.

Install

pip install whenful-mcp        # persistent install
uvx whenful-mcp                # one-shot ephemeral install

Requires Python 3.11+.

Setup

whenful-mcp setup

Walks through OAuth 2.1 authentication (opens your browser) and passphrase setup. Passphrase-derived key storage options, in order of preference:

• 1Password CLI (op) — biometric-gated retrieval
• OS Keychain (macOS / Linux Secret Service) — Touch ID / desktop-unlock gated
• Plaintext file — opt-in only via --insecure-key-storage

The setup flow writes:

• ~/.whenful/tokens.json — OAuth access + refresh tokens (mode 0600)
• A key entry in your chosen keystore — never the passphrase itself

Run

whenful-mcp           # default — runs the stdio server
whenful-mcp serve     # explicit equivalent

The server speaks the MCP stdio transport (line-delimited JSON-RPC on stdin/stdout). It's intended to be launched by an MCP client, not by hand.

Add to Claude Desktop

Edit your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS) and add:

{
  "mcpServers": {
    "whenful": {
      "command": "whenful-mcp"
    }
  }
}

Restart Claude Desktop. The Whenful tools (list_tasks, create_task, complete_task, recurring-instance management, analytics, and more) appear in the tool picker.

Sub-commands

Command	What it does
whenful-mcp setup	Interactive OAuth + passphrase setup
whenful-mcp serve	Run the stdio MCP server
whenful-mcp	Alias for serve
whenful-mcp --version	Show the installed version
whenful-mcp --help	Top-level usage
whenful-mcp setup --help	Setup-specific usage
whenful-mcp serve --help	Server-specific usage

Each sub-command supports --insecure-key-storage to allow the plaintext-file keystore fallback. Use it only on disposable VMs or if you know what you're doing — the keystore stores your AES-256 encryption key.

Privacy posture

• Zero telemetry. No usage tracking. No crash reports. No analytics.
• Local encryption key. Your passphrase derives the encryption key on your machine via PBKDF2-SHA256. The key never leaves your machine.
• Client-side decryption. Encrypted task content (title, description, domain name) decrypts on your machine, after the encrypted bytes arrive from the Whenful REST API over HTTPS.
• Open-source server (this package). The cloud REST API your client talks to is closed-source.

Source + docs

• Source: https://github.com/aleksandr-bogdanov/whenful
• Issues: https://github.com/aleksandr-bogdanov/whenful/issues
• MCP documentation: https://whenful.com/docs/mcp

License

Proprietary. See LICENSE in the source repository.