Super Productivity Local Bridge

[!IMPORTANT] This repository is archived. It has been superseded by the Go bridge.

The Go rewrite provides the same 16 operations, installs as a single binary with no Python or uv runtime to manage, and is where all further development happens. This repository is read-only: no further fixes, releases, or dependency updates.

New and existing installations should move to super-productivity-local-gobridge (docs, migration guide).

The content below describes the final Python release (v0.2.0) and is kept for reference.

Control Super Productivity tasks, projects, and tags from MCP hosts, CLI, and local automation tools — all through the desktop app's Local REST API.

Why

Super Productivity is a great task manager. This bridge lets AI coding agents and automation scripts interact with it programmatically — creating tasks, tracking work, and managing projects without leaving your workflow.

The bridge talks only to your local Super Productivity API on 127.0.0.1:3876. Your MCP host may have its own data handling, so review the host's privacy model before granting task access.

Features

• 16 operations — list/get/create/update/complete/uncomplete/start/stop/archive/restore tasks, current task get/set, list projects, list tags, status, health check, plus filters and time fields
• MCP adapter — live-validated with VS Code Copilot; includes setup guides and config generation for Claude Desktop and Codex CLI
• CLI — command-line access to common operations (health, status, list/get/create tasks, current task, projects, tags)
• Host config generator — prints ready-to-paste config with absolute paths for each supported host
• Doctor command — diagnoses connectivity and configuration issues

Install

Requires Python 3.11+ and uv.

git clone https://github.com/CameronBrooks11/super-productivity-local-bridge.git
cd super-productivity-local-bridge
scripts/install.sh

Use --dry-run to preview.

Alternatively, install from a GitHub Release wheel:

uv tool install https://github.com/CameronBrooks11/super-productivity-local-bridge/releases/download/v0.2.0/sp_local_bridge-0.2.0-py3-none-any.whl

Configure an MCP Host

sp-local-bridge-print-config vscode-copilot   # VS Code Copilot
sp-local-bridge-print-config claude-desktop    # Claude Desktop
sp-local-bridge-print-config codex             # Codex CLI

Add the printed snippet to the config file shown in the output, then restart the host.

See the host setup guides for detailed instructions.

Verify

sp-local-bridge-doctor

Safety

This bridge has write access to your Super Productivity data (create, update, complete, archive tasks). It talks only to localhost. task.delete is intentionally excluded. Back up your SP data before heavy automation use.

See Security for the full risk profile.

Documentation

Full docs: cameronbrooks11.github.io/super-productivity-local-bridge

• Getting Started
• Operations Reference
• Architecture
• Troubleshooting

Development

uv sync                     # Install deps
make check                  # Format, lint, typecheck, test, build
uv run pytest --cov         # Tests with coverage
uv run pre-commit install   # Git hooks

License

MIT