Skip to main content
Glama
Super Productivity REST MCP

Super Productivity REST MCP

by maystar

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

SP_REST_TOKEN

for authenticated tools

—

Bearer token from Super Productivity's Local REST API settings. Only sp_health works without it.

SP_REST_BASE_URL

no

http://host.docker.internal:3876

Base URL of the Local REST API. Use http://localhost:3876 when running next to Super Productivity on the same machine.

Running

Directly with Node (≥ 20.11)

npm install
SP_REST_TOKEN=... SP_REST_BASE_URL=http://localhost:3876 node index.js

As 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-mcp

Pre-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:latest

The 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:latest

Make 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

sp_health

Health check (unauthenticated)

sp_status

Current task + total task count

sp_tasks_list

List tasks, filterable by title/project/tag/done-state/source

sp_task_get

Get one task by id

sp_task_create

Create a task

sp_task_update

Update fields of a task

sp_task_delete

Delete a task

sp_task_start

Set a task as the current task

sp_task_archive

Archive a task

sp_task_restore

Restore an archived task

sp_task_control_get_current

Get the currently running task

sp_task_control_set_current

Set/clear the current task

sp_task_control_stop

Stop the current task

sp_focus_get

Focus Mode status (Flowtime/Pomodoro/Countdown)

sp_projects_list

List projects

sp_tags_list

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 instance

Testing

npm test

Runs 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.mjs

License

MIT

Available Tools

16 tools
sp_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

    B3.1/5.0

    Scored across 16 tools

    Disambiguation2/5

    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.

    Naming Consistency3/5

    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.

    Tool Count3/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.

    Completeness3/5

    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

    ActivityStale
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers