Connect an AI Assistant

Let an AI assistant on your computer read your tasks or add new ones through the desktop app's local MCP endpoint. It is off by default and entirely optional; Super Productivity works the same without it. For the full reference (tools, protocol, limits), see 3.01-API#assistant-access-mcp.

To add tasks from a cloud assistant (Claude web, ChatGPT) or from another device, use SuperSync's 3.01-API#agent-task-capture-mcp instead; the local endpoint is only reachable from this computer.

What you need

• The Super Productivity desktop app, running. The endpoint lives inside the app and stops when it closes. The web app and the Mac App Store build cannot serve it.
• An MCP client that supports HTTP servers with an Authorization header (all clients below do), or Claude Desktop with the extension.

Turn it on

1. Open Settings → Misc and switch on Enable assistant access (MCP, desktop only).
2. Choose what assistants may do. All permissions start off: Read tasks: titles, status, dates, projects and tags, Also read task notes (needs Read tasks) and Add new tasks to the Inbox.
3. Click Generate access key and copy it. It is shown once; if you lose it, replace it.
4. Pick your client below and paste the key where it says <key>. The settings panel also shows a ready-made Claude Code command with the key filled in.

The endpoint is http://127.0.0.1:3876/mcp in every recipe.

Recipes

Claude Code

Run in a terminal:

claude mcp add --scope user --transport http super-productivity http://127.0.0.1:3876/mcp --header "Authorization: Bearer <key>"

Claude Desktop (Windows, macOS)

Claude Desktop cannot add a local HTTP server, and its custom connectors run in the cloud, where 127.0.0.1 is not your computer. Use the extension:

1. Download super-productivity.mcpb (the settings panel links to it).
2. Open it with Claude Desktop, or drag it into Settings → Extensions.
3. Paste the access key when asked.

Codex

Add to ~/.codex/config.toml, then restart Codex:

[mcp_servers.super-productivity]
url = "http://127.0.0.1:3876/mcp"
bearer_token_env_var = "SP_ASSISTANT_KEY"

Set SP_ASSISTANT_KEY to the key in the environment Codex starts from, or replace the last line with http_headers = { Authorization = "Bearer <key>" }.

Cursor

Add to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "super-productivity": {
      "url": "http://127.0.0.1:3876/mcp",
      "headers": { "Authorization": "Bearer ${env:SP_ASSISTANT_KEY}" }
    }
  }
}

VS Code

Add to .vscode/mcp.json, or run MCP: Open User Configuration for all workspaces. VS Code asks for the key the first time and stores it securely:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "sp-assistant-key",
      "description": "Super Productivity access key",
      "password": true
    }
  ],
  "servers": {
    "super-productivity": {
      "type": "http",
      "url": "http://127.0.0.1:3876/mcp",
      "headers": { "Authorization": "Bearer ${input:sp-assistant-key}" }
    }
  }
}

Gemini CLI

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "super-productivity": {
      "httpUrl": "http://127.0.0.1:3876/mcp",
      "headers": { "Authorization": "Bearer <key>" }
    }
  }
}

LM Studio (local models)

In LM Studio, open Program → Install → Edit mcp.json and add:

{
  "mcpServers": {
    "super-productivity": {
      "url": "http://127.0.0.1:3876/mcp",
      "headers": { "Authorization": "Bearer <key>" }
    }
  }
}

With a model that runs on your computer, your task data never leaves it.

Other clients

Any MCP client that supports Streamable HTTP servers takes the URL http://127.0.0.1:3876/mcp and the header Authorization: Bearer <key>. Many accept the same JSON as the Cursor recipe.

Check the connection

Ask the assistant "What is the status of Super Productivity?". It calls get_status, which works with any permission and lists what the key may do. If it fails:

• Make sure the desktop app is running and the switch is on; the settings panel says whether the endpoint is running or why it is not. It shares port 3876 with the Local REST API (which you don't need to switch on); if another program uses that port, free it, then switch assistant access off and on again.
• 401 Unauthorized means the key is wrong or was replaced. Generate a new one and update the client.
• A client that can't see a tool lacks the permission for it. Change the permissions, then reconnect or restart the client so it reloads its tool list.

What stays local

• The endpoint: it listens on 127.0.0.1 only, so other devices on your network cannot reach it. Requests from web pages are refused.
• Super Productivity sends nothing. It answers the assistant on your computer and makes no network request of its own for this feature. There is no account, server or telemetry involved.
• The assistant decides where your data goes. Whatever it reads is passed to its model. With a cloud model (Claude, ChatGPT, Gemini, Copilot and most others), that provider receives it under its own privacy terms. With a local model (for example in LM Studio), it stays on your computer.
• Only what you allow is readable. Without Read tasks an assistant sees no existing data. Notes need their own permission. Archived tasks are never exposed.
• Settings and key: the switch and permissions apply to this computer only and are not synced. Only a hash of the key is stored; client configuration files and shell history hold the key itself, so prefer the environment-variable or prompt variants above where your client offers them.

Turn it off

Switch off Enable assistant access to stop the endpoint. To disconnect one client but keep others, there is a single key: replace it and give the new key only to the clients you want to keep.