Super-Productivity-MCP
MCP server that connects AI assistants to Super Productivity — manage tasks, projects, and tags through Claude, Kiro, or any MCP client
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/b0x42--super-productivity-mcp)HTML
<a href="/listings/b0x42--super-productivity-mcp"><img src="/api/listings/b0x42--super-productivity-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
1. Install the SP Plugin
**Option A — via npx:**
npx -y super-productivity-mcp@latest --extract-plugin
This command extracts `plugin.zip` to your current directory.
**Option B — manual download:** Download `plugin.zip` from the [latest release](https://github.com/b0x42/Super-Productivity-MCP/releases/latest).
Then in Super Productivity: **Settings → Plugins → Upload Plugin**, select `plugin.zip`, restart SP.
> **SP ≥ 18.13.0:** After enabling the plugin, SP shows a one-time **Node execution consent dialog**. Click **Allow** — the plugin requires Node access to communicate with the MCP server. Consent persists per device; only re-asked if you re-upload the plugin.
2. Configure Your MCP Client
{
"mcpServers": {
"super-productivity": {
"command": "npx",
"args": ["-y", "super-productivity-mcp"]
}
}
}Config file locations: - **Claude Desktop (macOS):** `~/Library/Application Support/Claude/claude_desktop_config.json` - **Claude Desktop (Windows):** `%APPDATA%\Claude\claude_desktop_config.json`
For **Claude Code**, don't edit the config file by hand — use the CLI:
# user scope (everywhere), project scope (-s project), or local scope (default) claude mcp add -s user super-productivity npx -- -y super-productivity-mcp
To verify, run `claude mcp list`. Restart the session to load the server. Swap `npx -- -y super-productivity-mcp` for `super-productivity-mcp` (global install) or `node /absolute/path/to/dist/index.js` (from source) — see [Running without npx](#running-without-npx).
3. Verify
Ask your AI assistant: *"Check the Super Productivity connection"*
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 270 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- <p align="center">
- <img src="plugin/icon.svg" width="128" height="128" alt="SP MCP Bridge icon">
- </p>
- <h1 align="center">Super Productivity MCP Server</h1>
- <p align="center">
- An MCP (Model Context Protocol) server that connects AI assistants to <a href="https://super-productivity.com">Super Productivity</a> — manage tasks, projects, and tags through Claude Desktop, Kiro, or any MCP-compatible client.
- </p>
- ## What You Can Do
- **✅ Quick Capture**
- > "Add a task: Buy milk #shopping @tomorrow 15m"
- Parses the tag, due date, and time estimate from short syntax — one shot, no follow-up needed.
- **🧹 Batch Triage**
- > "Show me all unscheduled tasks in my Work project, tag them #backlog, and set them due next Friday"
- Filters, bulk-updates due dates, and adds tags — all in one conversation turn.
- **🧠 Full Planning Session**
- > "Look at my week: show today's plan and anything overdue. Break 'Launch blog' into subtasks, start the first one, and move anything I finished yesterday to done. Give me a time summary when you're done."
- Reads resources for context, creates subtasks in batch, starts the timer, bulk-completes tasks, pulls the worklog, and summarizes — a multi-step workflow in a single prompt.
- → [More use cases](docs/use-cases.md)
- ## Installation
- ### 1. Install the SP Plugin
- **Option A — via npx:**
- ```bash
- npx -y super-productivity-mcp@latest --extract-plugin
- ```
- This command extracts `plugin.zip` to your current directory.
- **Option B — manual download:**
- Download `plugin.zip` from the [latest release](https://github.com/b0x42/Super-Productivity-MCP/releases/latest).
- Then in Super Productivity: **Settings → Plugins → Upload Plugin**, select `plugin.zip`, restart SP.
- > **SP ≥ 18.13.0:** After enabling the plugin, SP shows a one-time **Node execution consent dialog**. Click **Allow** — the plugin requires Node access to communicate with the MCP server. Consent persists per device; only re-asked if you re-upload the plugin.
- ### 2. Configure Your MCP Client
- ```json
- {
- "mcpServers": {
- "super-productivity": {
- "command": "npx",
- "args": ["-y", "super-productivity-mcp"]
- }
- }
- }
- ```
- Config file locations:
- - **Claude Desktop (macOS):** `~/Library/Application Support/Claude/claude_desktop_config.json`
- - **Claude Desktop (Windows):** `%APPDATA%\Claude\claude_desktop_config.json`
- For **Claude Code**, don't edit the config file by hand — use the CLI:
- ```bash
- # user scope (everywhere), project scope (-s project), or local scope (default)
- claude mcp add -s user super-productivity npx -- -y super-productivity-mcp
- ```
- To verify, run `claude mcp list`. Restart the session to load the server. Swap `npx -- -y super-productivity-mcp` for `super-productivity-mcp` (global install) or `node /absolute/path/to/dist/index.js` (from source) — see [Running without npx](#running-without-npx).
- ### 3. Verify
- Ask your AI assistant: *"Check the Super Productivity connection"*
- ## Running without npx
- `npx` is convenient but fetches the package on every cold cache and needs network access. If you'd rather pin a local copy, pick one of the options below.
- ### Option A — Global install
- ```bash
- npm install -g super-productivity-mcp
- super-productivity-mcp --extract-plugin # optional: write plugin.zip to cwd
- ```
- Then point your MCP client at the installed binary:
- ```json
- {
- "mcpServers": {
- "super-productivity": {
- "command": "super-productivity-mcp"
- }
- }
- }
- ```
- If the binary isn't found, your MCP client may not inherit your shell's `PATH`. Use the absolute path from `which super-productivity-mcp` as `command` — or, if `which` doesn't resolve it, point at `$(npm config get prefix)/bin/super-productivity-mcp` (on macOS/Linux).
- ### Option B — From source
- ```bash
- git clone https://github.com/b0x42/Super-Productivity-MCP.git
- cd Super-Productivity-MCP
- npm install
- npm run build # produces dist/index.js and dist/plugin.zip
- ```
- Then run the server directly with `node`:
- ```json
- {
- "mcpServers": {
- "super-productivity": {
- "command": "node",
- "args": ["/absolute/path/to/Super-Productivity-MCP/dist/index.js"]
- }
- }
- }
- ```
- The plugin to upload to Super Productivity is at `dist/plugin.zip` after `npm run build`.
- ## Prerequisites
- - [Super Productivity](https://super-productivity.com) >= 19.0.1
- - Node.js >= 18
- - An MCP-compatible client (Claude Desktop, Kiro, etc.)
- ## Available Tools
- | Tool | Description |
- |------|-------------|
- | `add_tag_to_task` | Add a tag without replacing other tags |
- | `bulk_complete_tasks` | Mark multiple tasks complete in one operation |
- | `bulk_update_tasks` | Update multiple tasks in one operation (incl. `priority`) |
- | `check_connection` | Verify SP is running and the plugin is responding |
- | `check_habit` | Check off a habit for a day (increments that day's value, defaults to today) |
- | `complete_task` | Mark a task as complete |
- | `create_habit` | Create a habit (streak-tracked click counter) |
- | `create_project` | Create a new project |
- | `create_tag` | Create a new tag |
- | `create_task` | Create a task (supports SP short syntax), optionally with `priority` (1 Low, 2 Medium, 3 High) |
- | `create_task_with_subtasks` | Create a parent task + subtasks in one operation, with optional `priority` on the parent and each subtask |
- | `debug_directories` | Show resolved data directory paths |
- | `delete_habit` | Permanently delete a habit |
- | `delete_project` | Permanently delete a project and all tasks it contains. Cannot delete the Inbox |
- | `delete_task` | Permanently delete a task (parent deletes subtasks too). Archived tasks can't be deleted — SP's plugin API is read-only for the archive |
- | `get_current_task` | Get the currently tracked task (null if none) |
- | `get_habits` | List all habits, including each one's computed streak length |
- | `get_projects` | List all projects |
- | `get_tags` | List all tags |
- | `get_task_repeat_cfgs` | List all recurring task configurations (schedule, cadence, day-of-week settings) |
- | `get_tasks` | List tasks — filter by project, tag, done, archived, search (title+notes), `parents_only`, `overdue`, `unscheduled`, `planned_for_today`, `recurring_only`, `fields` |
- | `get_worklog` | Time tracking summary for a date range |
- | `log_time` | Log time spent on a task — one day, or several at once via `entries` for backfill. Adds to each day's tracked time, or overwrites with `mode: "set"` |
- | `move_task_to_project` | Move a top-level task to a different project |
- | `move_tasks_backlog` | Move up to 100 top-level tasks between a project's regular list and its backlog (`destination: "backlog"` or `"regular"`). Validates the whole batch first; refuses moves into a backlog-disabled project (e.g. Inbox) |
- | `plan_tasks_for_today` | Batch plan/unplan tasks for today ⚠️ [limited](#known-limitations) |
- | `remove_tag_from_task` | Remove a single tag |
- | `reorder_tasks` | Reorder tasks within a project or parent. Rejects backlog tasks — use `move_tasks_backlog` |
- | `set_habit_value` | Set a habit's exact value for a day — backfill or correct history |
- | `show_notification` | Show a snackbar in SP's UI |
- | `start_task` | Start the time tracker on a task |
- | `stop_task` | Stop the currently running time tracker |
- | `update_habit` | Update habit title, icon, enabled state, or streak config |
- | `update_project` | Update project properties |
- | `update_tag` | Update tag properties |
- | `update_task` | Update title, notes, done state, due date, deadline, `priority` (1–3, `null` clears), `planned_at`, timed schedule (`due_with_time`) and reminder (`remind_at`) ⚠️ [limited](#known-limitations), time estimate, tags |
- Habit tools (`create_habit`, `get_habits`, `update_habit`, `check_habit`, `set_habit_value`, `delete_habit`) require a Super Productivity build newer than the `14.0.0` minimum above — on older builds they return a clear "requires a newer version" error instead of failing silently.
- ## Time Tracking
- Super Productivity stores time spent as a **per-day worklog** (`timeSpentOnDay`,
- a map of `YYYY-MM-DD` to milliseconds). The task's total, `timeSpent`, is always
- derived from it — SP recomputes the total on every write, and a parent task's
- time is the aggregate of its subtasks.
- This server follows that model:
- - **Reading** — both fields are available on `get_tasks`, including via field
- selection: `fields: ["timeSpent", "timeSpentOnDay"]`. They also appear in the
- `sp://tasks` resource summary. `get_worklog` aggregates the map across tasks
- by day, project, and tag.
- - **Writing** — through `log_time` only, which writes the day map and recomputes
- the total the way SP does. `update_task` and `bulk_update_tasks` deliberately
- cannot set `timeSpent`: writing a total that no worklog accounts for produces a
- task SP's own model cannot represent, and SP silently discards it at the next
- write to that task's time.
- ```jsonc
- // one day
- { "task_id": "abc", "duration": "1h30m" } // defaults to today
- // several days, e.g. backfilling a week
- { "task_id": "abc", "entries": [
- { "date": "2026-08-30", "duration": "2h" },
- { "date": "2026-08-31", "duration": "45m" }
- ] }
- ```
- If a task's stored total disagreed with its worklog before the write — which
- happens with data imported from other tools — `log_time` recomputes from the
- worklog and reports the old value as `previousTimeSpent`, so the correction is
- visible rather than silent.
- ## Tool Call Timeline
- The plugin adds a **MCP Bridge** pane to Super Productivity's menu listing what
- the assistant has done — one row per tool call with the time, tool name,
- duration, and whether it succeeded. Click a row to see the arguments it was
- called with and the result it returned; failures show the error message.
- The server writes each call to `tool-calls.jsonl` in the same data directory it
- uses for IPC (`debug_directories` shows the path). The log keeps the most recent
- 500 calls and is created mode 0600. Individual arguments or results over 8KB are
- replaced by a marker recording how many bytes were elided, so a `get_tasks` over
- a large task list doesn't copy your database into a flat file.
- Recording is best-effort: if the log can't be written, the tool call still
- succeeds and returns normally.
- ## SP Short Syntax
- Include these in task titles and they are parsed automatically:
- | Syntax | Example | Effect |
- |--------|---------|--------|
- | `#tag` | `Buy milk #shopping` | Adds the "shopping" tag |
- | `+project` | `Fix bug +work` | Assigns to "work" project (prefix match, min 3 chars) |
- | `@due` | `Report @friday` | Sets due date to Friday |
- | `@due time` | `Call @tomorrow 3pm` | Sets due date and time |
- | `30m` | `Quick fix 30m` | Sets 30-minute time estimate |
- | `1h/2h` | `Research 1h/2h` | Sets 1h spent, 2h estimate |
- | `p1` / `p2` / `p3` | `Fix bug p1` | Sets priority: p1 = High, p2 = Medium, p3 = Low (`create_task` only). Opposite order from the `priority` parameter, where 3 = High |
- ## Troubleshooting
- **Plugin not loading?** Two common causes:
- - **SP 18.6.0–18.9.x cold-boot race:** toggle the plugin off and on in Settings → Plugins (no restart needed on ≥ 18.6.0).
- - **SP 18.10.0–18.12.x hard block:** update to SP ≥ 18.13.0. After re-uploading the plugin, accept the Node execution consent dialog that appears on first enable.
- **Commands timing out?** Ask *"Show debug info for Super Productivity"* to check that both sides are using the same data directory. Mac App Store users may need to set `SP_MCP_DATA_DIR`.
- → [Full troubleshooting guide](docs/troubleshooting.md)
- ## Known Limitations
- | Tool | Issue | Status |
- |------|-------|--------|
- | `plan_tasks_for_today` | Sets `plannedAt` on the task but does not add it to SP's internal Planner store, so the task may not appear in the Today view. | Upstream request: [super-productivity#7495](https://github.com/super-productivity/super-productivity/issues/7495) |
- | `create_project` / `update_project` | `folder_id` can be set or cleared, but there's no way to list folders through this server — the plugin API exposes no folder getter. Get the ID from the Super Productivity UI. | Upstream request: [super-productivity#9600](https://github.com/super-productivity/super-productivity/issues/9600) |
- | `update_task` | `remind_at` can be set but not cleared — SP's plugin API validates `remindAt` as a plain `number` and rejects `null`. | Constraint of SP's plugin API, no upstream request filed |
- ## Local deployment documentation
- For a pinned source-based macOS deployment, see:
- - [macOS setup and operations](docs/macos-setup.md)
- - [Troubleshooting](docs/troubleshooting.md)
- For local development, the `Makefile` wraps the `npm run build`/`typecheck`/`lint`/`test` steps above with dependency tracking — see `AGENTS.md`.
- ## License
- MIT
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.