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.