super-productivity-rest-mcp
This server lets Claude or any MCP client control Super Productivity through its Local REST API using 15 MCP tools.
Check connectivity and status:
sp_healthverifies the REST API is reachable;sp_get_statusreturns the current task and task counts.List and search tasks:
sp_list_tasksfilters by title, project, tag, source (active/archived/all), and includes/excludes completed tasks.Get task details:
sp_get_taskretrieves a single task by ID.Create tasks:
sp_create_taskcreates tasks with title, notes, project, tags, due dates, estimates, planned time, time spent, done state, and optionalparentIdfor subtasks.Update tasks:
sp_update_taskedits title, notes, project, tags, due dates, estimates, planned time, time spent, and done state (but not parent/subtask relationships).Delete tasks:
sp_delete_taskpermanently removes a task.Archive and restore tasks:
sp_archive_taskarchives a task;sp_restore_taskbrings an archived task back.Control the current/running task:
sp_start_taskmakes a task current;sp_set_current_tasksets or clears the current task;sp_stop_current_taskstops it;sp_get_current_taskshows what is currently active.List projects and tags:
sp_list_projectsandsp_list_tagsoptionally filter by title.
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 Show my tasks for today"
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 Super Productivity's built-in Local REST API as MCP tools — so Claude (or any other MCP client) can list, create, update, archive and control your tasks, projects and tags through plain conversation.
Two transports, two branches — pick the one your client needs
main(this branch) — stdio. The client spawns the server as a local subprocess. This is what you want for Claude Code.
http-transport— Streamable HTTP onhttp://127.0.0.1:3877/mcp, run as a long-lived local service. Use it for Claude Cowork / Claude Desktop, which reach it through themcp-remotebridge.Same 15 tools and the same Local REST API underneath — only the transport differs.
Why this exists
Super Productivity ships with a Local REST API (http://127.0.0.1:3876), but it doesn't speak MCP — it's a plain REST API. This project is a thin, direct translation layer between the two, with a few design choices that set it apart from other Super Productivity MCP integrations:
Talks directly to the official Local REST API — no Super Productivity plugin to install, no Node-execution permission to grant, no file-based polling. One HTTP request per tool call.
Full coverage of everything the Local REST API exposes: task CRUD (including delete), archive/restore, current-task control (start/stop/set/get), projects, tags, and health/status — 15 tools total, mapped 1:1 to the API's endpoints.
Handles the access-token variant. Some Super Productivity versions require a bearer token for the Local REST API and some don't — this server supports both via an optional environment variable.
Zero extra runtime dependencies beyond Node.js — no Python, no Super Productivity plugin bundle.
Related MCP server: Super-Productivity-MCP
Prerequisites
Super Productivity desktop app (Electron — the Local REST API is not available in the web version)
Node.js 18+
An MCP client that can spawn a local (stdio) server — this README focuses on Claude Code. For clients that connect by URL instead, see the
http-transportbranch.
1. Enable the Local REST API in Super Productivity
Go to Settings → Misc → Enable local REST API. This starts a server on http://127.0.0.1:3876 (the port is fixed and not configurable). It only accepts connections from localhost.
Check whether your installation also requires an access token:
curl -i http://127.0.0.1:3876/tasks200 OKwith a task list → no token needed, skip theSP_REST_TOKENparts below.401 Unauthorized→ copy the token from Settings → Misc → Access Token; you'll need it in step 3.
2. Install
git clone https://github.com/mrswer/super-productivity-rest-mcp.git
cd super-productivity-rest-mcp
npm install3. Register with Claude Code
The server's name must come before the --scope/-e flags, or the CLI misparses the following arguments as more environment variables.
Without a token:
claude mcp add super-productivity --scope user -- node /absolute/path/to/super-productivity-rest-mcp/server.jsWith a token:
claude mcp add super-productivity --scope user -e SP_REST_TOKEN=your-token-here -- node /absolute/path/to/super-productivity-rest-mcp/server.js--scope user registers the server for every project, in both the claude CLI and the Claude Code UI (they share the same ~/.claude.json).
Verify:
claude mcp list
# super-productivity: node /path/to/server.js - ✔ ConnectedOther MCP clients
Any client that supports local stdio servers works the same way — point it at node /absolute/path/to/server.js, and set SP_REST_TOKEN (and optionally SP_REST_BASE_URL) in its environment-variable configuration if needed. See .env.example for the variables this server reads (note: it does not load .env files automatically — your MCP client must pass real environment variables).
Note on clients that connect by URL: this branch speaks stdio only, so a client that wants an MCP endpoint rather than a subprocess — Claude Cowork and Claude Desktop among them — cannot use it. The
http-transportbranch serves the same tools over Streamable HTTP on localhost for exactly that case. Either way the server must run on the same machine as Super Productivity.
Usage
Ask your MCP client things like:
"Show my tasks for today"
"Create a task 'Review PR #42' in the Work project"
"What's my currently running task?"
"Mark task X as done"
By default, sp_list_tasks excludes completed tasks (includeDone defaults to false), matching a typical "what's left to do" view. Ask for "including completed tasks" if you want the full count to match what Super Productivity's UI shows for the day.
Available tools
Tool | Description |
| Check whether the Local REST API is reachable and ready |
| Get the current task and task counts |
| List tasks, filterable by title, project, tag, completion state, source |
| Get a single task by id |
| Create a task (supports subtasks via |
| Update a task's title, notes, project, tags, estimate, due date, etc. |
| Delete a task |
| Start a task (set as current) |
| Archive a task |
| Restore an archived task |
| Get the currently active task, if any |
| Set or clear the current task |
| Stop the current task |
| List projects, optionally filtered by title |
| List tags, optionally filtered by title |
Environment variables
Variable | Required | Default | Description |
| Only if your Super Productivity requires it | — | Bearer token from Settings → Misc → Access Token |
| No |
| Override if running the server on a different host than Super Productivity |
Troubleshooting
Symptom | Likely cause | Fix |
| Wrong path to | Check the path ( |
"Could not reach Super Productivity's Local REST API" | Super Productivity isn't running, or the Local REST API is disabled | Start Super Productivity, enable it in Settings → Misc |
| This installation requires a token that isn't configured | Get the token from Settings → Misc → Access Token, pass it as |
| Argument order — | Put the server name right after |
Task counts don't match the Super Productivity UI | Completed tasks are excluded by default | Ask for "including completed tasks" |
Security notes
The Local REST API only accepts connections from
127.0.0.1— it is not reachable from other machines unless you deliberately expose it (not recommended).This server runs as a local subprocess over stdio; it is not a network service and doesn't listen on any port itself.
Treat your
SP_REST_TOKEN, if you have one, like any other credential — don't commit it, and pass it via your MCP client's environment-variable configuration rather than hardcoding it.
Limitations
Requires the Super Productivity desktop app (Electron) — the Local REST API isn't available in the web build.
This branch uses stdio transport only. If your client needs an HTTP endpoint, use the
http-transportbranch instead of building your own wrapper.Re-parenting a task (moving it under a different parent) isn't supported by the underlying Local REST API — this is a limitation of Super Productivity's API, not this server.
Contributing
Issues and PRs are welcome. If you hit a bug or want a tool that Super Productivity's Local REST API supports but this server doesn't yet expose, open an issue.
Support
If this project saved you some time, you're welcome to buy me a coffee ☕.
License
MIT — see LICENSE.
Available Tools
15 toolssp_archive_taskC
Archive a Super Productivity task.
Inputs: id (required).
sp_create_taskC
Create a new task in Super Productivity.
Inputs: title (required), notes, dueDay, isDone, +7 more.
sp_delete_taskB
Delete a Super Productivity task.
Inputs: id (required).
sp_get_current_taskA
Get the task that is currently active/running in Super Productivity, if any.
Inputs: no named parameters.
sp_get_statusA
Get the current task and task counts from Super Productivity.
Inputs: no named parameters.
sp_get_taskA
Get a single Super Productivity task by its id.
Inputs: id (required).
sp_healthB
Check whether the Super Productivity Local REST API is reachable and ready.
Inputs: no named parameters.
sp_list_projectsA
List Super Productivity projects, optionally filtered by title.
Inputs: query.
sp_list_tagsA
List Super Productivity tags, optionally filtered by title.
Inputs: query.
sp_list_tasksB
List tasks from Super Productivity, optionally filtered by title, project, tag or completion state.
Inputs: query, tagId, source, projectId, +1 more.
sp_restore_taskA
Restore a previously archived Super Productivity task.
Inputs: id (required).
sp_set_current_taskB
Set (or clear) the currently active task in Super Productivity.
Inputs: taskId (required).
sp_start_taskB
Start a task (set it as the current/active task) in Super Productivity.
Inputs: id (required).
sp_stop_current_taskA
Stop the currently active task in Super Productivity (no task remains current).
Inputs: no named parameters.
sp_update_taskB
Update an existing Super Productivity task. Note: parentId and subTaskIds cannot be changed this way.
Inputs: id (required), notes, title, dueDay, +7 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Tools are mostly distinct, but start_task and set_current_task have overlapping functionality; descriptions clarify their purposes.
Most tools follow the 'sp_verb_noun' pattern, but 'sp_health' deviates from this convention, which is a minor inconsistency.
15 tools is appropriate for a task management server, covering CRUD, workflow actions, and auxiliary features without being excessive.
Tasks are comprehensively covered, but tags and projects only have list operations, missing create/update/delete for those entities.
Maintenance
Related MCP Connectors
Manage Superlist tasks and lists in plain language from any MCP-compatible AI agent.
Official Todoist MCP server. Manage tasks and projects. Hosted, no API key needed.
Unofficial community ClickUp MCP via personal API token. Not affiliated with ClickUp.
Official Akiflow MCP for tasks, calendars, scheduling, time slots, and meeting transcripts.
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
- AlicenseNot gradedqualityAmaintenanceAn MCP server that connects AI assistants to Super Productivity for managing tasks, projects, and tags. Supports quick capture, batch triage, and full planning sessions through natural language.327 npm137MIT
- AlicenseBqualityDmaintenanceEnables interaction with Super Productivity's local REST API to manage tasks, projects, and time tracking through natural language.15327 npmMIT
- AlicenseAqualityCmaintenanceAn MCP server that connects ChatGPT Desktop or Codex to Super Productivity's local REST API, enabling explicit task selection, planning, timer control, and completion via natural language.1026 npmMIT