Super Productivity — MCP Server

Integrates Claude with Super Productivity using the Model Context Protocol. This server targets the desktop app's Local REST API on http://127.0.0.1:3876.

Only tested on macOS. Contributions and bug reports are welcome!

Structure

src/
├── index.ts          ← entry point, starts the MCP server
├── sp-client.ts      ← wrapper for Super Productivity REST API
├── resources.ts      ← resources readable by Claude (tasks, projects, tags)
├── prompts.ts        ← reusable prompt templates
└── tools/
    ├── tasks.ts      ← CRUD tools for tasks
    └── projects.ts   ← tools for projects and tags

Setup

1. Install dependencies

npm install

2. Build

npm run build
# or use watch mode during development:
npm run dev

3. Enable the API in Super Productivity

In Super Productivity → Settings → Misc → Enable local REST API. The desktop app listens on 127.0.0.1:3876.

4. Register in Claude Desktop

Open ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows) and add the block from claude_desktop_config.snippet.json, replacing /ABSOLUTE/PATH/ with the real project path:

{
  "mcpServers": {
    "super-productivity": {
      "command": "/usr/local/bin/node",
      "args": ["/absolute/path/super-productivity-mcp/dist/index.js"],
      "env": {
        "SP_API_URL": "http://127.0.0.1:3876"
      }
    }
  }
}

Restart Claude Desktop. You should see the 🔧 icon in chat — this means the tools are active.

4a. Quick smoke test

Before opening Claude, verify the local API:

curl http://127.0.0.1:3876/health
curl http://127.0.0.1:3876/tasks

5. (Optional) Debug with MCP Inspector

npm run inspect

This opens a web interface for manually testing each tool.

Available Tools

Tool	Description
health_check	Checks that the local REST API is up and ready
list_tasks	Lists tasks with optional filters (query, projectId, projectName, tagId, tagName, includeDone, source)
search_tasks	Searches tasks by title text with the same optional filters
get_task	Retrieves the details of a single task
get_status	Returns current status: active task and task counts
get_current_task	Returns the currently running task
create_task	Creates a new task; accepts projectName and tagNames in addition to IDs
update_task	Updates fields of an existing task; also supports projectName and tagNames
complete_task	Marks a task as completed
start_task	Starts a task as the current task
set_current_task	Sets or clears the current task
stop_current_task	Stops the current task
archive_task	Archives a task
restore_task	Restores an archived task
delete_task	Deletes a task
get_projects	Lists projects
get_tags	Lists tags

Available Resources

URI	Description
sp://status	Current status in text format
sp://tasks/active	Active tasks in text format
sp://tasks/archived	Archived tasks in text format
sp://task/current	Current task in JSON
sp://projects	All projects in JSON
sp://tags	All tags in JSON

Available Prompts

Name	Description
daily-planning	Daily planning session
weekly-review	Weekly review
break-down-task	Breaks down a complex task into subtasks

Environment Variables

Variable	Default	Description
SP_API_URL	http://127.0.0.1:3876	Base URL for the Super Productivity API

Development

npm test

This runs the TypeScript build and the Node test suite.