tasqr-mcp (Python)

tasqr-mcp (Python)

Tasqr MCP server — task state management for AI agents.

Runs as a local stdio process that reads your API key from ~/.config/tasqr/credentials and proxies tool calls to the Tasqr Lambda MCP server. Your MCP client config holds no secrets — the API key lives only in the credentials file (written 0600 on Mac/Linux; on Windows it relies on your profile directory's ACLs).

Install

Requires Python 3.11 or newer.

uvx tasqr-mcp        # run once without installing
# or
pip install tasqr-mcp

MCP client config

{
  "mcpServers": {
    "tasqr": {
      "command": "uvx",
      "args": ["tasqr-mcp"]
    }
  }
}

Credentials

First run — no setup needed. Run the proxy once in a terminal:

uvx tasqr-mcp

With no API key on disk, it starts GitHub device-flow signup: it opens your browser to GitHub, copies the device code to your clipboard to paste in, and (if your account has more than one workspace) asks which to use. It then writes the credentials file for you. You only need the manual steps below if you'd rather create it yourself.

Your MCP client never sees a secret — it just launches uvx tasqr-mcp, and the key is read from:

~/.config/tasqr/credentials   (Mac/Linux)
%APPDATA%\tasqr\credentials   (Windows)

[default]
api_key = tasqr_abc123...

On Mac/Linux the file is written 0600 (owner read/write only); on Windows it inherits your profile directory's ACLs. Sign up at tasqr.ai if you'd prefer to grab a key from the web instead.

Because the signup is interactive, it only runs when stdin is a TTY. An MCP client launching the proxy headlessly with no key will exit and tell you to run uvx tasqr-mcp in a terminal first.

Logging

Logging is off by default — nothing is written to disk unless you turn it on. When enabled, the proxy keeps an append-only JSON-lines event log recording metadata only: tool names and field names, never task content, never key material.

Turn it on in the credentials file:

[default]
api_key   = tasqr_abc123...
log_level = info                        # off (default) | info | debug
log_path  = ~/.config/tasqr/tasqr-mcp.log

There is no rotation or size cap, so debug is for troubleshooting, not for leaving on.

Environment variables

Env vars win over the credentials file, which wins over the defaults.

Client-side encryption (BYOK)

Encrypt task fields (title, description, metadata, output, note) locally before they reach Tasqr servers. Requires an AWS KMS key you control.

Add kms_key_id to your credentials file to turn it on — nothing else to install:

[default]
api_key      = tasqr_abc123...
kms_key_id   = arn:aws:kms:us-east-1:123456789012:key/your-key-id
aws_profile  = default

Your Tasqr org must be enrolled in client-side BYOK. At startup the proxy asks the server which mode your org uses. If the org is server-managed, it refuses to start rather than encrypt — the server would otherwise encrypt your ciphertext a second time, leaving the data unreadable to the dashboard, the REST API, and any other agent, and unrecoverable if you lost your KMS key. The error tells you which profile to fix.

Once enrolled, the proxy fetches or generates a data encryption key (DEK), wraps it with KMS, and stores the wrapped key in the Tasqr API. Later runs unwrap the cached DEK with a single KMS call. All AES-256-GCM encryption happens in memory — the plaintext DEK never leaves the process.

Every ciphertext is additionally bound to its context: the GCM associated data ties each encrypted value to your org, its task, and the field it was written for. A blob moved to any other slot — a different field, task, or org — fails decryption outright instead of decrypting in the wrong place. To make this possible the proxy mints each new task's id itself and sends it with the create call.

See the client-side encryption guide for the full setup walkthrough.

Local development

pip install -e ".[dev]"
pytest
tasqr-mcp --version