Super Productivity REST MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Super Productivity REST MCP list all tasks tagged 'urgent' in the Work project"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Super Productivity REST MCP
An MCP server that exposes the Super Productivity desktop app's Local REST API as tools an MCP client (e.g. Claude Code) can call directly — list/create/update/delete tasks, start/stop/archive them, read status and Focus Mode state, and list projects and tags.
It talks to the REST API over plain HTTP and makes no assumption about how it's deployed: run it
locally next to Super Productivity, in a container that reaches the host over
host.docker.internal, or anywhere else that can reach the API's base URL.
Prerequisites
Super Productivity ≥ 14.0.0, with Settings → Misc → Enable local REST API turned on. Copy the
access token shown there — you'll need it as SP_REST_TOKEN below.
Related MCP server: Super Productivity MCP Server
Configuration
Env var | Required | Default | Description |
| for authenticated tools | — | Bearer token from Super Productivity's Local REST API settings. Only |
| no |
| Base URL of the Local REST API. Use |
Running
Directly with Node (≥ 20.11)
npm install
SP_REST_TOKEN=... SP_REST_BASE_URL=http://localhost:3876 node index.jsAs a Docker container
docker build -t super-productivity-rest-mcp .
docker run -i --rm \
-e SP_REST_TOKEN=... \
-e SP_REST_BASE_URL=http://host.docker.internal:3876 \
super-productivity-rest-mcpPre-built images are published to GHCR on every push to main and on version tags — see
.github/workflows/docker-publish.yml. Once published:
docker run -i --rm -e SP_REST_TOKEN=... ghcr.io/<owner>/super-productivity-rest-mcp:latestThe server communicates over stdio, so -i (keep stdin open) is required; it does not open any
network port of its own.
Registering with Claude Code
# Local Node process
claude mcp add super-productivity --scope user -- node /path/to/index.js
# Or via Docker
claude mcp add super-productivity --scope user -- \
docker run -i --rm -e SP_REST_TOKEN -e SP_REST_BASE_URL ghcr.io/<owner>/super-productivity-rest-mcp:latestMake sure SP_REST_TOKEN (and SP_REST_BASE_URL, if needed) is present in the environment Claude
Code's MCP client subprocess inherits.
Tools
Tool | Description |
| Health check (unauthenticated) |
| Current task + total task count |
| List tasks, filterable by title/project/tag/done-state/source |
| Get one task by id |
| Create a task |
| Update fields of a task |
| Delete a task |
| Set a task as the current task |
| Archive a task |
| Restore an archived task |
| Get the currently running task |
| Set/clear the current task |
| Stop the current task |
| Focus Mode status (Flowtime/Pomodoro/Countdown) |
| List projects |
| List tags |
Project layout
index.js entry point: reads env config, connects the server to stdio
src/server.js builds the McpServer and wires all tool modules to a REST client
src/rest-client.js thin HTTP client for the Local REST API (no MCP knowledge)
src/tool-result.js shared helpers for shaping tool call results/errors
src/tools/*.js one module per resource (tasks, task-control, focus, projects, tags, health)
test/smoke.mjs automated test: server + in-memory MCP client, no network required
test/manual-client.mjs manual verification client against a real, running Super Productivity instanceTesting
npm testRuns test/smoke.mjs: connects an in-memory MCP client to the server, checks the expected 16
tools are registered, and confirms a call against an unreachable backend fails as a reported tool
error rather than crashing. This needs no real Super Productivity instance and is what CI runs.
To verify against a real instance, run:
SP_REST_TOKEN=... [SP_REST_BASE_URL=http://localhost:3876] node test/manual-client.mjsLicense
Available Tools
16 toolssp_focus_getGet Focus Mode statusA
Returns the mode (Flowtime/Pomodoro/Countdown), cycle, and running timer, if active.
Inputs: no named parameters.
sp_healthSuper Productivity: health checkA
Checks whether the Super Productivity Local REST API is reachable (unauthenticated).
Inputs: no named parameters.
sp_projects_listList projectsA
Lists projects, optionally filtered by title (case-insensitive).
Inputs: query.
sp_statusSuper Productivity: statusB
Returns the current task and the total task count.
Inputs: no named parameters.
sp_tags_listList tagsA
Lists tags, optionally filtered by title (case-insensitive).
Inputs: query.
sp_task_archiveArchive a taskC
Moves a task to the archive.
Inputs: id (required).
sp_task_control_get_currentGet the currently running taskB
Returns the currently running task (task-control).
Inputs: no named parameters.
sp_task_control_set_currentSet the current taskA
Sets the current task; omitting taskId (or passing null) clears the current task.
Inputs: taskId.
sp_task_control_stopStop the current taskA
Stops the currently running task without starting another one.
Inputs: no named parameters.
sp_task_createCreate a taskA
Creates a new task. A subtask (parentId set) inherits the parent's project and cannot have its own tags.
Inputs: title (required), notes, dueDay, isDone, +10 more.
sp_task_deleteDelete a taskB
Deletes a task irreversibly.
Inputs: id (required).
sp_task_getGet a single taskA
Returns one task by id.
Inputs: id (required).
sp_task_restoreRestore a task from the archiveC
Restores an archived task.
Inputs: id (required).
sp_tasks_listList tasksB
Lists tasks, optionally filtered by title, project, tag, done-state and source.
Inputs: query, tagId, source, projectId, +1 more.
sp_task_startStart a taskC
Sets the given task as the current task.
Inputs: id (required).
sp_task_updateUpdate a taskB
Updates individual fields of a task. parentId/subTaskIds cannot be changed (results in 400). deadlineDay/deadlineWithTime/deadlineRemindAt are mutually exclusive.
Inputs: id (required), notes, title, dueDay, +10 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
Several tools overlap around the 'current task' concept: sp_task_start, sp_task_control_set_current, sp_task_control_stop, sp_status, and sp_task_control_get_current all describe the same state from slightly different angles. This makes it unclear which tool an agent should select for starting, stopping, or querying the active task.
The sp_ prefix is consistent, but naming patterns vary: sp_task_get and sp_tasks_list mix singular/plural, while sp_task_start vs sp_task_control_set_current and sp_health/sp_status break the verb_noun rhythm. The names are readable but not predictable enough to be a 4 or 5.
16 tools is on the borderline of being heavy for the scope, and the redundant current-task control tools make the count feel inflated. It is not excessive, but several tools could be consolidated without losing capability.
Tasks have solid lifecycle coverage with create, get, list, update, delete, archive, restore, start, and stop. However, projects and tags only have list operations, and focus only has a getter, leaving no way to manage those resources through the MCP server.
Maintenance
Related MCP Connectors
Local-first task manager: create, edit, and complete tasks, projects, and checklists via MCP.
Unofficial community ClickUp MCP via personal API token. Not affiliated with ClickUp.
Official Todoist MCP server. Manage tasks and projects. Hosted, no API key needed.
Headless task management for bots, apps and AI agents. Remote MCP server, OAuth or access token.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceBridge between Super Productivity app and MCP servers, allowing Claude Desktop to directly interact with Super Productivity for task management, project organization, and information retrieval.132MIT
- AlicenseAqualityDmaintenanceEnables Claude to interact with Super Productivity's local REST API for task, project, and tag management, including CRUD operations, status checks, and daily planning prompts.17MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage TickTick tasks, projects, habits, and focus sessions through the MCP server.71 PyPI148MIT
- AlicenseBqualityDmaintenanceEnables interaction with Super Productivity's local REST API to manage tasks, projects, and time tracking through natural language.15327 npmMIT