Super Productivity MCP

An explicit, local Model Context Protocol server for Super Productivity. It connects ChatGPT Desktop or Codex to Super Productivity's official local REST API over STDIO.

The core promise is deliberately small:

Select one task explicitly, put it in Today, start or stop its timer, and complete it.

Nothing is imported or scheduled implicitly. GitHub issue association is opt-in per tool call.

Quick start

The complete first-run path takes a few minutes:

1. Install the Super Productivity desktop app 18.x or newer. The web and mobile apps do not expose this local API. If Enable local REST API is missing, update the desktop app from the official releases.

2. In Super Productivity, open Settings → Misc Settings and enable Enable local REST API. With the released 18.16.0 desktop app, no token is displayed and no token is required.

3. Choose exactly one host setup below. Do not run the CLI command if you use a Desktop application.

   Case A — Desktop application:

   • ChatGPT Desktop: open Settings → MCP servers → Add server → STDIO, enter command npx, and add the two arguments -y and super-productivity-mcp-server.
   • Codex Desktop: it may not show an MCP servers menu. Open Settings → Configuration, choose Open config.toml, and paste the configuration block in the Codex Desktop section below. No CLI is required.

   Case B — Codex CLI: open the CLI section below, verify codex --version, and then run the exact codex mcp add command. If Terminal says zsh: command not found: codex, use the Codex Desktop config.toml path in Case A instead.

   For Super Productivity 18.16.0, leave SP_API_TOKEN unset. If a future build displays an Access Token, supply it only through the MCP environment; never paste it into a chat or commit it.

4. Restart or reload the MCP host after completing your selected case, then ask it:

   Check the connection to Super Productivity with check_connection.
   

5. Once the connection succeeds, use search_tasks to find one task and pass its returned taskId explicitly to plan_task_today, start_task, stop_timer, or complete_task.

Optional local liveness check (it does not require the token):

curl --noproxy 127.0.0.1 http://127.0.0.1:3876/health

The expected response contains "server":"up" and "rendererReady":true.

What it does

Tool	Purpose	Changes state
health / check_connection	Check the local API and renderer	No
search_tasks	Find tasks and return stable IDs	No
list_today	List tasks already planned for Today	No
plan_task_today	Plan exactly one supplied task ID for Today	Yes
start_task	Start exactly one supplied task ID	Yes
stop_timer	Stop the current timer	Yes
complete_task	Complete exactly one supplied task ID	Yes
get_current_task	Read the currently tracked task	No
ensure_github_issue_task	Reuse or create one task for a GitHub issue	Yes, only when called

The server intentionally does not create GitHub issues. Use the GitHub integration or connector for that, then call ensure_github_issue_task only when you explicitly want the issue in Super Productivity.

The workflow

flowchart LR
    A["ChatGPT Desktop or Codex"] -->|STDIO MCP| B["Super Productivity MCP"]
    B -->|"Loopback HTTP; no token in 18.16.0"| C["Super Productivity local REST API"]
    C --> D["One selected task"]
    D --> E["Today"]
    E --> F["Timer"]
    F --> G["Done"]
    H["GitHub issue URL or owner/repo#number"] -->|explicit ensure call| B

Typical conversation:

Search Super Productivity for "Add the export filter".
Plan task <returned taskId> for Today.
Start task <same taskId>.
Stop the timer.
Complete task <same taskId>.

The server instructions tell an MCP client to search first and pass the exact returned taskId to every state-changing operation. There is no bulk-selection fallback.

Requirements

• Super Productivity desktop 18.x or newer with the local REST API enabled.
• Node.js 20 or newer.

In Super Productivity, enable Settings → Misc Settings → Enable local REST API. The official API listens on http://127.0.0.1:3876 by default and exposes an unauthenticated /health endpoint. The released 18.16.0 desktop API is also unauthenticated for task endpoints, so no token is needed for the normal setup. This server sends a Bearer token only when the optional SP_API_TOKEN is set, to remain compatible with future authenticated builds.

Read the official Super Productivity local REST API documentation before changing the API URL or exposing a proxy. The upstream API is release-sensitive: this package's no-token default matches the 18.16.0 desktop release, whose released API handler does not authenticate task requests.

Install

From the public npm registry:

npx -y super-productivity-mcp-server

End users do not need an npm account or an npm login to install the public package.

For a local checkout:

pnpm install
pnpm build
node /absolute/path/to/super-productivity-mcp/dist/index.js

Package and releases

The public package is super-productivity-mcp-server. The GitHub release workflow publishes new versions when the repository has an NPM_TOKEN Actions secret. That maintainer-only credential is not needed by people installing or using the server.

The server reads configuration from environment variables:

Variable	Default	Notes
SP_API_TOKEN	—	Optional Bearer token for an authenticated Super Productivity build
SP_API_URL	http://127.0.0.1:3876	HTTP(S) URL; loopback is enforced by default
SP_API_TIMEOUT_MS	15000	Integer from 1000 to 60000
SP_ALLOW_NON_LOOPBACK_URL	false	Use only for a trusted local proxy
SP_LOG_LEVEL	warn	error, warn, info, or debug

See .env.example for a copyable template.

Case A — Desktop application

There are two Desktop applications people commonly mean here. They do not expose the same menu:

• ChatGPT Desktop: has the graphical Settings → MCP servers menu.
• Codex Desktop: some builds may not have an MCP menu. Use Settings → Configuration → Open config.toml instead.

Both variants start the same public npm package. You do not need an npm account or an npm login.

A1. ChatGPT Desktop — graphical setup

Use this exact procedure in the ChatGPT Desktop application:

1. Open Settings → MCP servers.

2. Click Add server.

3. Choose STDIO.

4. Fill the fields as follows:

   Field	Value
   Name, if requested	super_productivity
   Command	npx
   Arguments	-y and super-productivity-mcp-server as two separate arguments
   SP_API_URL, optional	http://127.0.0.1:3876
   SP_LOG_LEVEL, optional	warn
   SP_API_TOKEN	Leave empty for Super Productivity 18.16.0

5. Save the server and select Restart or restart ChatGPT Desktop if requested.

6. In a chat, type /mcp to inspect connected servers, then ask:

   Check the connection to Super Productivity with check_connection.
   

If MCP servers or STDIO is unavailable in ChatGPT Desktop, update the application or use the Codex Desktop configuration path below. For a local build, replace the command with node and use the absolute path to dist/index.js. See examples/chatgpt-desktop.md.

A2. Codex Desktop — configure config.toml, not an MCP menu

If your Codex Desktop build does not show an MCP servers menu, do not look for it elsewhere in the settings. Use Settings → Configuration → Open config.toml instead:

1. Open Settings.

2. Select Configuration in the left sidebar.

3. Select Open config.toml.

4. Add this block and save the file:

   [mcp_servers.super_productivity]
   command = "npx"
   args = ["-y", "super-productivity-mcp-server"]
   env = { SP_API_URL = "http://127.0.0.1:3876", SP_LOG_LEVEL = "warn" }
   

5. Fully quit and reopen Codex Desktop.

6. Ask Codex:

   Check the connection to Super Productivity with check_connection.
   

The shared file is normally ~/.codex/config.toml. Codex Desktop, Codex CLI, and the IDE extension use the same configuration layers. For a local checkout, replace the block with:

[mcp_servers.super_productivity]
command = "node"
args = ["/absolute/path/to/super-productivity-mcp/dist/index.js"]

Case B — Codex CLI in Terminal

Use this case only if you want to work from the Codex CLI. The Desktop procedure above does not require the codex command.

1. In the same Terminal where you will use Codex, run:

   codex --version
   

   If Terminal prints zsh: command not found: codex, stop and use Case A. If you specifically want the CLI, install it using the official Codex CLI instructions, open a new Terminal, and run codex --version again.

2. Once codex --version works, copy this complete command:

   codex mcp add super_productivity --env SP_API_URL=http://127.0.0.1:3876 --env SP_LOG_LEVEL=warn -- npx -y super-productivity-mcp-server
   

3. Verify the registration and start the CLI:

   codex mcp list
   codex
   

4. Inside Codex, type /mcp and ask:

   Check the connection to Super Productivity with check_connection.
   

See examples/codex-config.toml for the shared configuration format and the official OpenAI MCP setup documentation for the current Codex configuration surfaces.

Troubleshooting

I cannot find “Enable local REST API”

Confirm that you are using the desktop app, not the web or mobile app, and that its version is 18.x or newer. Quit and update it from the official Super Productivity releases, then return to Settings → Misc Settings. This setting is not present in older desktop builds.

I can enable the API, but I do not see a token

That is expected with the released Super Productivity 18.16.0 desktop app. Its local API is bound to loopback and does not require a token, so leave SP_API_TOKEN unset. Do not use an npm or GitHub token in its place. A future Super Productivity build may expose an Access Token; use it only when the app itself displays one.

In check_connection, configured: true means the local API and renderer are ready. The separate tokenConfigured: false field is expected for this no-token setup.

ECONNREFUSED 127.0.0.1:3876

Super Productivity is closed, the local API is disabled, or the renderer has not finished starting. Keep the desktop app open, enable the API, wait a few seconds, and retry check_connection.

401 Unauthorized

This only applies when using a Super Productivity build that requires a Bearer token. Copy the current Access Token from that app, set it as SP_API_TOKEN, and restart the MCP host. Do not use the npm publication token here.

The server does not appear in the MCP client

Check that Node.js 20 or newer is installed, that the command is exactly npx with arguments -y super-productivity-mcp-server, and restart the MCP host. The server speaks MCP over STDIO, so normal diagnostics go to stderr rather than appearing as a regular terminal application.

Terminal says zsh: command not found: codex

That message only means the optional Codex CLI is unavailable in that Terminal. If you use the Codex Desktop application, configure the server from Settings → Configuration → Open config.toml; no codex command is needed. If you intended to use the CLI, follow the official Codex CLI installation instructions, open a new Terminal, and confirm codex --version before running codex mcp add.

I cannot find “MCP servers” in Desktop settings

That menu belongs to the ChatGPT Desktop MCP flow. The current Codex Desktop settings panel may not expose it. In Codex Desktop, select Configuration in the settings sidebar and then choose Open config.toml. Add the [mcp_servers.super_productivity] block from Case A, restart Codex Desktop, and ask it to call check_connection.

check_connection succeeds but no tasks are returned

Use search_tasks with a distinctive part of an existing task title. State-changing tools require the exact taskId returned by that search; the server never guesses a task or bulk-imports issues.

GitHub issue association

Call the tool explicitly with either form:

ensure_github_issue_task({ issue: "Amorem/my-repo#123" })
ensure_github_issue_task({ issue: "https://github.com/Amorem/my-repo/issues/123", planToday: true })

The server searches active, archived, and completed local tasks. It reuses a task containing its stable marker or exact issue URL. If no safe match exists, it creates one task with a marker and returns its ID. Repeating the same call is idempotent. planToday defaults to false and must be set explicitly.

The current Super Productivity local REST API does not expose writable GitHub provider fields in its task PATCH allowlist. For that reason, tasks created by this server use a private, visible-in- notes marker; native GitHub-linked tasks are recognized when the local API exposes an unambiguous GitHub issue number. If two native tasks could match, the server returns an ambiguity error instead of choosing silently. No GitHub token or GitHub network request is required by this server.

Security model

• STDIO stdout is reserved for MCP protocol messages; diagnostics go to stderr.
• SP_API_TOKEN is optional; when supplied, it is never printed and is redacted in error/log paths.
• The configured API URL must be loopback unless SP_ALLOW_NON_LOOPBACK_URL=true is explicitly set.
• Super Productivity 18.16.0's local API has no application-level authentication. Keep the API on loopback and remember that local applications running as the same user can read and modify tasks.
• If a future build provides a local API token, protect the environment and configuration that can access it.
• The server does not import all GitHub issues, poll GitHub, or perform background actions.
• All task mutations require an exact taskId, except the explicit, idempotent GitHub association tool which creates at most one marked task.

Architecture

sequenceDiagram
    participant Host as ChatGPT Desktop / Codex
    participant MCP as super-productivity-mcp-server
    participant SP as Super Productivity

    Host->>MCP: search_tasks({query})
    MCP->>SP: GET /tasks?query=...
    SP-->>MCP: task list with IDs
    MCP-->>Host: IDs and safe summaries
    Host->>MCP: plan_task_today({taskId})
    MCP->>SP: PATCH /tasks/:id {dueDay: today}
    Host->>MCP: start_task({taskId})
    MCP->>SP: POST /tasks/:id/start
    Host->>MCP: stop_timer() / complete_task({taskId})
    MCP->>SP: POST /task-control/stop or PATCH /tasks/:id

Implementation boundaries are intentionally narrow:

• src/sp-client.ts is the typed, timeout-bound REST client.
• src/server.ts contains MCP schemas and explicit tool behavior.
• src/github.ts parses and deduplicates issue references without GitHub network access.
• src/config.ts, src/errors.ts, and src/logger.ts enforce safe configuration and diagnostics.

Development

pnpm install
pnpm verify

pnpm verify runs lint, formatting checks, strict TypeScript typechecking, unit/integration tests, and the production build. The test suite uses mocked REST responses and the official MCP SDK's in-memory transport; it never contacts Super Productivity or GitHub.

See CONTRIBUTING.md for the contribution workflow and SECURITY.md for vulnerability reports.

Roadmap

• Add a safe provider-aware lookup when Super Productivity exposes issue-provider configuration via the local API.
• Add optional GitHub metadata enrichment behind an explicit, separately configured connector.
• Add a small interactive setup command that validates the local API without storing the token.
• Add compatibility fixtures for each supported Super Productivity API revision.

License

MIT. See LICENSE.