Skip to main content
Glama
super-productivity-rest-mcp

super-productivity-rest-mcp

by mrswer

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.

License: MIT Node

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 on http://127.0.0.1:3877/mcp, run as a long-lived local service. Use it for Claude Cowork / Claude Desktop, which reach it through the mcp-remote bridge.

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-transport branch.

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/tasks
  • 200 OK with a task list → no token needed, skip the SP_REST_TOKEN parts 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 install

3. 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.js

With 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 - ✔ Connected

Other 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-transport branch 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

sp_health

Check whether the Local REST API is reachable and ready

sp_get_status

Get the current task and task counts

sp_list_tasks

List tasks, filterable by title, project, tag, completion state, source

sp_get_task

Get a single task by id

sp_create_task

Create a task (supports subtasks via parentId)

sp_update_task

Update a task's title, notes, project, tags, estimate, due date, etc.

sp_delete_task

Delete a task

sp_start_task

Start a task (set as current)

sp_archive_task

Archive a task

sp_restore_task

Restore an archived task

sp_get_current_task

Get the currently active task, if any

sp_set_current_task

Set or clear the current task

sp_stop_current_task

Stop the current task

sp_list_projects

List projects, optionally filtered by title

sp_list_tags

List tags, optionally filtered by title

Environment variables

Variable

Required

Default

Description

SP_REST_TOKEN

Only if your Super Productivity requires it

—

Bearer token from Settings → Misc → Access Token

SP_REST_BASE_URL

No

http://127.0.0.1:3876

Override if running the server on a different host than Super Productivity

Troubleshooting

Symptom

Likely cause

Fix

✘ Failed to connect in claude mcp list

Wrong path to server.js, or dependencies not installed

Check the path (claude mcp get super-productivity), run npm install in the project directory

"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

401 Unauthorized / "Authorization token required"

This installation requires a token that isn't configured

Get the token from Settings → Misc → Access Token, pass it as SP_REST_TOKEN (see step 3)

Invalid environment variable format: <server-name> when running claude mcp add

Argument order — -e before the server name

Put the server name right after add, before --scope/-e

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-transport branch 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 tools
sp_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

    A3.5/5.0

    Scored across 15 tools

    Disambiguation4/5

    Tools are mostly distinct, but start_task and set_current_task have overlapping functionality; descriptions clarify their purposes.

    Naming Consistency4/5

    Most tools follow the 'sp_verb_noun' pattern, but 'sp_health' deviates from this convention, which is a minor inconsistency.

    Tool Count5/5

    15 tools is appropriate for a task management server, covering CRUD, workflow actions, and auxiliary features without being excessive.

    Completeness4/5

    Tasks are comprehensively covered, but tags and projects only have list operations, missing create/update/delete for those entities.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Bridge between Super Productivity app and MCP servers, allowing Claude Desktop to directly interact with Super Productivity for task management, project organization, and information retrieval.
      132
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      An 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 npm
      137
      MIT