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

On a Mac, Homebrew is a third option, and the requirement above doesn't apply to it — the formula wraps this same sdist in its own virtualenv with its own Python, so it shares nothing with any Python you have installed:

brew tap tasqrai/tasqr
brew trust --tap tasqrai/tasqr
brew install tasqr-mcp

Installed this way the command is plain tasqr-mcp, so use that in place of uvx in the client config below. Full install notes are in the tap, tasqrai/homebrew-tasqr.

Related MCP server: keyvault

MCP client config

The entry is the same in every client; only where it lives differs. Most clients accept it per project or for every project, and a per-project entry wins where both exist.

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

Claude Code

The Tasqr plugin adds this for you (/plugin marketplace add tasqrai/tasqr-claude-code-plugin, then /plugin install tasqr@tasqr). To add it by hand:

claude mcp add --scope project tasqr -- uvx tasqr-mcp   # .mcp.json in the project, shareable via git
claude mcp add --scope user tasqr -- uvx tasqr-mcp      # ~/.claude.json, every project

Cursor

.cursor/mcp.json in the project, or ~/.cursor/mcp.json for every project. Cursor › Settings › MCP shows the servers it loaded.

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

Claude Desktop

Settings › Developer › Edit Config opens claude_desktop_config.json (~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows). Global only; restart Claude Desktop after saving.

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

Google Antigravity

.agents/mcp_config.json in the workspace, or ~/.gemini/config/mcp_config.json for every workspace (shared by the IDE and the CLI). The agent panel's MCP Servers › Manage MCP Servers › View raw config opens the global file.

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

Amazon Kiro

.kiro/settings/mcp.json in the workspace, or ~/.kiro/settings/mcp.json for every workspace. The command palette has "Kiro: Open workspace MCP config (JSON)" and "Kiro: Open user MCP config (JSON)".

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

Amazon Quick Desktop

Settings › Capabilities › MCP › Add MCP. Either add a local server with the command and arguments from the entry above, or choose Import and point it at a Kiro or Claude Code config file that already contains the entry.

Anything else

Any MCP client that can launch a stdio server takes the same entry: a command, no URL, no headers, no key.

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