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.
1 maintainer
Metadata
1 maintainer
Release files for whenful-mcp 0.6.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| whenful_mcp-0.6.4-py3-none-any.whl | Python 3 | none | any | Details |
Release files / whenful_mcp-0.6.4-py3-none-any.whl
| Download URL | whenful_mcp-0.6.4-py3-none-any.whl |
|---|---|
| Size | 144.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4c3c6a692232bd6596cd2ab206d5e7eb502c261518389765f5269c973c1e187b
|
|
BLAKE2b-256 checksum How to use checksums |
04d08b92bc562a70b3b20fc596c9c538cd9d074abe35334337fb37d45e4e97ba
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Security for whenful-mcp 0.6.4
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
