Metadata-Version: 2.4
Name: whenful-mcp
Version: 0.5.1
Summary: Local MCP server for Whenful — encrypted task access via Claude Desktop and other MCP clients.
Project-URL: Homepage, https://whenful.com
Project-URL: Source, https://github.com/aleksandr-bogdanov/whenful
Project-URL: Issues, https://github.com/aleksandr-bogdanov/whenful/issues
Author-email: Alex Bogdanov <alex@bogdanov.wtf>
License: Proprietary
Keywords: ai-assistant,claude,mcp,task-management,whenful
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Scheduling
Requires-Python: >=3.11
Requires-Dist: cryptography>=44.0.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: keyring>=24
Requires-Dist: mcp[cli]>=1.26.0
Requires-Dist: pydantic>=2
Description-Content-Type: text/markdown

# whenful-mcp

Local Model Context Protocol (MCP) server for [Whenful](https://whenful.com).
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

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

Requires Python 3.11+.

## Setup

```bash
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

```bash
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:

```jsonc
{
  "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.
