tasks-manager-mcp

📥 Download the Tasks Manager app at tasks-manager.com. This package is the companion MCP server — it needs the desktop app installed and running to do anything.

Standalone MCP server for the Tasks Manager desktop app. Read tasks by code/id/title (with native images) and create/update tasks programmatically, straight from any MCP host (Claude Code, Claude Desktop, etc.).

Get the app first: the landing page and downloads live at https://tasks-manager.com. Install and run the app, then add this MCP server to your host as described below.

It opens the running app's SQLite DB directly, so it must run on the same host as the app — do not run it inside a container (the prebuilt better-sqlite3 binary must match the host arch). See DB location.

Install

Install the command globally:

npm i -g tasks-manager-mcp

Update later with npm i -g tasks-manager-mcp@latest.

Node 20+ required. better-sqlite3 12.x ships prebuilt binaries for macOS (arm64/x64), Windows (x64), and Linux (x64/arm64) on Node 20/22/23/24/25, so npm i -g needs no compiler on those platforms. On an unsupported platform/Node combo it falls back to building from source, which needs a C++ toolchain (Xcode CLT / build-essential / MSVC Build Tools).

Register with an MCP host

Add to your host's MCP config (e.g. claude_desktop_config.json):

{ "mcpServers": { "tasks-manager": { "command": "tasks-manager-mcp" } } }

Or register with Claude Code from the CLI:

claude mcp add --scope user tasks-manager -- tasks-manager-mcp

GUI hosts and PATH: apps launched from the macOS Dock/Finder (e.g. Claude Desktop) don't inherit your shell PATH, so a bare tasks-manager-mcp may be "not found." If so, use the absolute path from which tasks-manager-mcp (typically /opt/homebrew/bin/tasks-manager-mcp) as command. Terminal-launched hosts like Claude Code aren't affected.

Tools

Read

• list_spaces() — every workspace, with the count of accessible vs locked projects in each.
• list_projects({space?, include_archived?}) — browse projects, optionally scoped to one space.
• find_task(query) — fuzzy find by code (OCOI-4), numeric id, task number, or title substring.
• get_task(identifier) — full task detail in one call: every column, the description markdown, project/space/section, parent + direct-subtask summaries, tags/labels, and every finding including its full markdown body. Images referenced in the description (both task-media:// URLs and inline data:image/...;base64,... URIs) are attached as native image content blocks so Claude sees them directly without a separate Read call. There is no separate "fetch a finding" tool — get_task is the whole picture.
• list_tasks({project?, status?, tag?, limit?}) — browse tasks.

Findings are the separate markdown notebook entries (investigation notes, decisions, context kept next to a task without polluting the description). get_task returns them in full; use add_task_finding (below) to append one.

Locked projects are invisible to every tool. If a project has lock_enabled = 1 in the app, MCP cannot enumerate it, see its tasks, or write to it. list_projects does report a hidden_locked_count so callers know one exists. Unlock the project in the app to expose it to MCP.

Write

• create_task({project, title, description?, status?, priority?, assignee?, due_date?, parent_task?, task_code?, tags?, labels?}) — create a new task. project accepts a code prefix (TMTA), numeric id, or unique name substring. Tags/labels must already exist in the project's space. The next code in the project sequence is auto-generated unless task_code is set.
• update_task({identifier, title?, description?, status?, priority?, assignee?, due_date?, parent_task?, task_code?, tags?, labels?}) — partial update by code or id. assignee / due_date / parent_task accept null to clear. Changing status auto-remaps the task to that status's default section. tags / labels REPLACE the task's set when present.
• add_task_finding({task, title, content?}) — append a new finding to a task. Use when the user asks you to capture investigation notes, decisions, or context next to a task without editing the main description.

Writes are gated by default — you can turn the gate off. Out of the box, every create_task, update_task, and add_task_finding pops a native macOS dialog (via osascript) showing the planned change and waits for you to click Create / Update or Cancel. The gate lives inside the MCP server itself, not in per-project rules, so the default applies to every host and project without you repeating a rule per-project — and while it's on, a prompt alone can't skip it.

It is opt-out, not mandatory. Set TASKS_MANAGER_MCP_AUTO_CONFIRM=1 in the server's environment and every write commits immediately with no dialog — the gate is disabled for that server, by your own choice.

Letting an agent fully take over (no per-write prompts)

If you want an agent to create and update tasks autonomously without a dialog interrupting every write, set TASKS_MANAGER_MCP_AUTO_CONFIRM=1 in the server's env:

{
  "mcpServers": {
    "tasks-manager": {
      "command": "tasks-manager-mcp",
      "env": { "TASKS_MANAGER_MCP_AUTO_CONFIRM": "1" }
    }
  }
}

With this set, writes apply silently — the agent has full write access to every unlocked project. Only do this on a machine you trust to follow your own rules, and remember that locked projects remain invisible and unwritable regardless of this setting. To restore the confirmation prompts, remove the variable (or set it to anything other than 1).

On non-macOS platforms the confirmation dialog isn't available, so writes error out unless TASKS_MANAGER_MCP_AUTO_CONFIRM=1 is set — on Linux/Windows this variable is effectively required to write at all.

DB location

Auto-resolved. Override with TASKS_MANAGER_DB=<path>:

| OS | Path | | ------- | ----------------------------------------------------------------- | | macOS | ~/Library/Application Support/tasks-manager/tasks-manager.db | | Windows | %APPDATA%/tasks-manager/tasks-manager.db | | Linux | ~/.config/tasks-manager/tasks-manager.db |

Concurrency

The server now opens the DB read-write. Both processes (the running Electron app and this server) can read freely under WAL mode; writes are serialized by SQLite's writer lock. Foreign keys are enforced on this connection. After writes from this server, refresh the app's view to see the changes — the renderer caches don't auto-invalidate.

Smoke test

node test.mjs

Runs create + update against an in-memory DB and asserts the rows look right. Useful when modifying helpers.