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.

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.

Prerequisites

• Super Productivity desktop app (Electron — the Local REST API is not available in the web version)

• Node.js 18+

• An MCP client — this README focuses on Claude Code, but any MCP client that supports local (stdio) servers will work

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 remote/cloud chat clients: this server uses stdio transport and must run on the same machine as Super Productivity. It will not work with a cloud-hosted chat client (e.g. a browser-based Claude session) that requires a remote https:// MCP endpoint — only with clients that can spawn a local process, such as Claude Code.

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

Environment variables

Troubleshooting

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.

• Uses stdio transport only; there is no bundled HTTP/remote transport. If you need to reach this from a cloud-hosted MCP client, you'd need to front it with your own HTTP transport and a tunnel — out of scope for this project.

• 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.