Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/b0x42--super-productivity-mcp/badge.svg)](/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

i

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.

  1. <p align="center">
  2. <img src="plugin/icon.svg" width="128" height="128" alt="SP MCP Bridge icon">
  3. </p>
  4. <h1 align="center">Super Productivity MCP Server</h1>
  5. <p align="center">
  6. 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.
  7. </p>
  8. ## What You Can Do
  9. **✅ Quick Capture**
  10. > "Add a task: Buy milk #shopping @tomorrow 15m"
  11. Parses the tag, due date, and time estimate from short syntax — one shot, no follow-up needed.
  12. **🧹 Batch Triage**
  13. > "Show me all unscheduled tasks in my Work project, tag them #backlog, and set them due next Friday"
  14. Filters, bulk-updates due dates, and adds tags — all in one conversation turn.
  15. **🧠 Full Planning Session**
  16. > "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."
  17. 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.
  18. → [More use cases](docs/use-cases.md)
  19. ## Installation
  20. ### 1. Install the SP Plugin
  21. **Option A — via npx:**
  22. ```bash
  23. npx -y super-productivity-mcp@latest --extract-plugin
  24. ```
  25. This command extracts `plugin.zip` to your current directory.
  26. **Option B — manual download:**
  27. Download `plugin.zip` from the [latest release](https://github.com/b0x42/Super-Productivity-MCP/releases/latest).
  28. Then in Super Productivity: **Settings → Plugins → Upload Plugin**, select `plugin.zip`, restart SP.
  29. > **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.
  30. ### 2. Configure Your MCP Client
  31. ```json
  32. {
  33. "mcpServers": {
  34. "super-productivity": {
  35. "command": "npx",
  36. "args": ["-y", "super-productivity-mcp"]
  37. }
  38. }
  39. }
  40. ```
  41. Config file locations:
  42. - **Claude Desktop (macOS):** `~/Library/Application Support/Claude/claude_desktop_config.json`
  43. - **Claude Desktop (Windows):** `%APPDATA%\Claude\claude_desktop_config.json`
  44. For **Claude Code**, don't edit the config file by hand — use the CLI:
  45. ```bash
  46. # user scope (everywhere), project scope (-s project), or local scope (default)
  47. claude mcp add -s user super-productivity npx -- -y super-productivity-mcp
  48. ```
  49. 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).
  50. ### 3. Verify
  51. Ask your AI assistant: *"Check the Super Productivity connection"*
  52. ## Running without npx
  53. `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.
  54. ### Option A — Global install
  55. ```bash
  56. npm install -g super-productivity-mcp
  57. super-productivity-mcp --extract-plugin # optional: write plugin.zip to cwd
  58. ```
  59. Then point your MCP client at the installed binary:
  60. ```json
  61. {
  62. "mcpServers": {
  63. "super-productivity": {
  64. "command": "super-productivity-mcp"
  65. }
  66. }
  67. }
  68. ```
  69. 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).
  70. ### Option B — From source
  71. ```bash
  72. git clone https://github.com/b0x42/Super-Productivity-MCP.git
  73. cd Super-Productivity-MCP
  74. npm install
  75. npm run build # produces dist/index.js and dist/plugin.zip
  76. ```
  77. Then run the server directly with `node`:
  78. ```json
  79. {
  80. "mcpServers": {
  81. "super-productivity": {
  82. "command": "node",
  83. "args": ["/absolute/path/to/Super-Productivity-MCP/dist/index.js"]
  84. }
  85. }
  86. }
  87. ```
  88. The plugin to upload to Super Productivity is at `dist/plugin.zip` after `npm run build`.
  89. ## Prerequisites
  90. - [Super Productivity](https://super-productivity.com) >= 19.0.1
  91. - Node.js >= 18
  92. - An MCP-compatible client (Claude Desktop, Kiro, etc.)
  93. ## Available Tools
  94. | Tool | Description |
  95. |------|-------------|
  96. | `add_tag_to_task` | Add a tag without replacing other tags |
  97. | `bulk_complete_tasks` | Mark multiple tasks complete in one operation |
  98. | `bulk_update_tasks` | Update multiple tasks in one operation (incl. `priority`) |
  99. | `check_connection` | Verify SP is running and the plugin is responding |
  100. | `check_habit` | Check off a habit for a day (increments that day's value, defaults to today) |
  101. | `complete_task` | Mark a task as complete |
  102. | `create_habit` | Create a habit (streak-tracked click counter) |
  103. | `create_project` | Create a new project |
  104. | `create_tag` | Create a new tag |
  105. | `create_task` | Create a task (supports SP short syntax), optionally with `priority` (1 Low, 2 Medium, 3 High) |
  106. | `create_task_with_subtasks` | Create a parent task + subtasks in one operation, with optional `priority` on the parent and each subtask |
  107. | `debug_directories` | Show resolved data directory paths |
  108. | `delete_habit` | Permanently delete a habit |
  109. | `delete_project` | Permanently delete a project and all tasks it contains. Cannot delete the Inbox |
  110. | `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 |
  111. | `get_current_task` | Get the currently tracked task (null if none) |
  112. | `get_habits` | List all habits, including each one's computed streak length |
  113. | `get_projects` | List all projects |
  114. | `get_tags` | List all tags |
  115. | `get_task_repeat_cfgs` | List all recurring task configurations (schedule, cadence, day-of-week settings) |
  116. | `get_tasks` | List tasks — filter by project, tag, done, archived, search (title+notes), `parents_only`, `overdue`, `unscheduled`, `planned_for_today`, `recurring_only`, `fields` |
  117. | `get_worklog` | Time tracking summary for a date range |
  118. | `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"` |
  119. | `move_task_to_project` | Move a top-level task to a different project |
  120. | `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) |
  121. | `plan_tasks_for_today` | Batch plan/unplan tasks for today ⚠️ [limited](#known-limitations) |
  122. | `remove_tag_from_task` | Remove a single tag |
  123. | `reorder_tasks` | Reorder tasks within a project or parent. Rejects backlog tasks — use `move_tasks_backlog` |
  124. | `set_habit_value` | Set a habit's exact value for a day — backfill or correct history |
  125. | `show_notification` | Show a snackbar in SP's UI |
  126. | `start_task` | Start the time tracker on a task |
  127. | `stop_task` | Stop the currently running time tracker |
  128. | `update_habit` | Update habit title, icon, enabled state, or streak config |
  129. | `update_project` | Update project properties |
  130. | `update_tag` | Update tag properties |
  131. | `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 |
  132. 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.
  133. ## Time Tracking
  134. Super Productivity stores time spent as a **per-day worklog** (`timeSpentOnDay`,
  135. a map of `YYYY-MM-DD` to milliseconds). The task's total, `timeSpent`, is always
  136. derived from it — SP recomputes the total on every write, and a parent task's
  137. time is the aggregate of its subtasks.
  138. This server follows that model:
  139. - **Reading** — both fields are available on `get_tasks`, including via field
  140. selection: `fields: ["timeSpent", "timeSpentOnDay"]`. They also appear in the
  141. `sp://tasks` resource summary. `get_worklog` aggregates the map across tasks
  142. by day, project, and tag.
  143. - **Writing** — through `log_time` only, which writes the day map and recomputes
  144. the total the way SP does. `update_task` and `bulk_update_tasks` deliberately
  145. cannot set `timeSpent`: writing a total that no worklog accounts for produces a
  146. task SP's own model cannot represent, and SP silently discards it at the next
  147. write to that task's time.
  148. ```jsonc
  149. // one day
  150. { "task_id": "abc", "duration": "1h30m" } // defaults to today
  151. // several days, e.g. backfilling a week
  152. { "task_id": "abc", "entries": [
  153. { "date": "2026-08-30", "duration": "2h" },
  154. { "date": "2026-08-31", "duration": "45m" }
  155. ] }
  156. ```
  157. If a task's stored total disagreed with its worklog before the write — which
  158. happens with data imported from other tools — `log_time` recomputes from the
  159. worklog and reports the old value as `previousTimeSpent`, so the correction is
  160. visible rather than silent.
  161. ## Tool Call Timeline
  162. The plugin adds a **MCP Bridge** pane to Super Productivity's menu listing what
  163. the assistant has done — one row per tool call with the time, tool name,
  164. duration, and whether it succeeded. Click a row to see the arguments it was
  165. called with and the result it returned; failures show the error message.
  166. The server writes each call to `tool-calls.jsonl` in the same data directory it
  167. uses for IPC (`debug_directories` shows the path). The log keeps the most recent
  168. 500 calls and is created mode 0600. Individual arguments or results over 8KB are
  169. replaced by a marker recording how many bytes were elided, so a `get_tasks` over
  170. a large task list doesn't copy your database into a flat file.
  171. Recording is best-effort: if the log can't be written, the tool call still
  172. succeeds and returns normally.
  173. ## SP Short Syntax
  174. Include these in task titles and they are parsed automatically:
  175. | Syntax | Example | Effect |
  176. |--------|---------|--------|
  177. | `#tag` | `Buy milk #shopping` | Adds the "shopping" tag |
  178. | `+project` | `Fix bug +work` | Assigns to "work" project (prefix match, min 3 chars) |
  179. | `@due` | `Report @friday` | Sets due date to Friday |
  180. | `@due time` | `Call @tomorrow 3pm` | Sets due date and time |
  181. | `30m` | `Quick fix 30m` | Sets 30-minute time estimate |
  182. | `1h/2h` | `Research 1h/2h` | Sets 1h spent, 2h estimate |
  183. | `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 |
  184. ## Troubleshooting
  185. **Plugin not loading?** Two common causes:
  186. - **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).
  187. - **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.
  188. **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`.
  189. → [Full troubleshooting guide](docs/troubleshooting.md)
  190. ## Known Limitations
  191. | Tool | Issue | Status |
  192. |------|-------|--------|
  193. | `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) |
  194. | `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) |
  195. | `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 |
  196. ## Local deployment documentation
  197. For a pinned source-based macOS deployment, see:
  198. - [macOS setup and operations](docs/macos-setup.md)
  199. - [Troubleshooting](docs/troubleshooting.md)
  200. For local development, the `Makefile` wraps the `npm run build`/`typecheck`/`lint`/`test` steps above with dependency tracking — see `AGENTS.md`.
  201. ## License
  202. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.