Claude Desktop MCP Extension

Connect 2Do for Mac to Claude Desktop to find tasks, plan projects, and organize your work. You can ask Claude to create a packing checklist, review upcoming deadlines, or arrange tasks into sections without writing a script.

In 2Do, this integration is called Claude Co-Work. The extension uses MCP, a standard that lets AI apps use tools. Other MCP clients that support local stdio servers can use the same 2Do server.

Requirements

• 2Do for Mac with the 2Do Automation Suite. You can check for this suite in 2Do's AppleScript dictionary.
• Claude Desktop for Mac with desktop extension support.

Keep 2Do running while you use the extension. If the app or a password-protected list is locked, unlock it in 2Do before asking Claude to access that data.

Installing the Extension

Step 1: Download the extension

Download the latest 2do.<version>.mcpb file from the 2Do extension releases page.

Step 2: Install it in Claude Desktop

In Claude Desktop, open Settings > Extensions > Advanced settings, click Install Extension…, and select the downloaded file.

If your organization manages Claude Desktop, its settings may limit which extensions you can install. See Claude's desktop extension guide for installation and administrator settings.

Step 3: Review the installation prompt

Claude Desktop may show a broad access warning for a manually installed extension. The 2Do extension provides tools to read and change data in 2Do and to open items in the app. Read Privacy and Security for how that data reaches Claude, then click Install to continue.

Step 4: Try a request

Open 2Do, start a new chat in Claude Desktop, and ask: "List my 2Do lists."

Once Claude returns your lists, try one of the requests below. After updating the app or extension, start a new chat so Claude loads the current tools.

note

When testing an unreleased version, use the extension package supplied with that app build. An older app may reject commands or arguments added by a newer extension.

What You Can Do

Describe what you want to do and name the relevant list, section, or task. For example:

• "Show me the first 10 unfinished tasks due this week, with the earliest due first."
• "Create a packing checklist in my Travel list, with tasks for my passport, charger, and medication."
• "Create Bookings and Packing sections in my Travel list, then put the packing checklist in Packing."
• "Move the Packing section above Bookings."
• "Move the Packing section and its tasks to my Summer Trip list."
• "Pause my Waiting tag, then show me which tasks it hides."

Claude can also find List Groups, Smart Lists, tags, tag groups, and locations; edit task dates, notes, priorities, alarms, recurrence, and actions; and complete, duplicate, or delete tasks. It can open a task in 2Do or select a list or built-in Focus view.

Each command that changes data is one Edit > Undo step in 2Do, including commands that change several tasks. A command that makes no change adds no undo step.

Organizing Tasks into Sections

Sections group tasks within a normal list. You can ask Claude to create a section, add tasks to it, move tasks to another section, reorder the sections, or move a whole section to another list. These tools require extension version 0.2.0 or later and a 2Do build that supports section automation.

Create a section and add tasks

Ask Claude to create the section in a named list, then create or move tasks into it. A section can have a title and an optional description. Titles do not have to be unique, so the tools use the section_id returned by 2Do to identify each section.

For clients making tool calls directly:

1. Use list_lists to get the list's list_id.
2. Call create_section with that list_id and a title, or call list_sections to find an existing section.
3. Pass its section_id to create_task or move_task. The section already identifies the destination list; do not also pass list_id or parent_task_id.

move_task accepts one task_id or a batch of task_ids. Moving a project or checklist keeps its children together. Moving a sub-task into a section makes it a top-level task.

Change or clear a task's section

Use move_task with the destination section_id to move tasks between sections, including sections in different lists.

For a top-level task staying in its current list, update_task also accepts section_id. Send section_id:null to remove the task from its section while keeping it in the list. Omit the field to leave the section unchanged. Moving a task to its current list_id leaves its section unchanged too.

Reorder or move whole sections

To reorder sections, call list_sections, then pass every returned section_id exactly once to reorder_sections, in the desired order. This changes the section order; tasks keep their membership and follow the list's sort setting. The unsectioned area and Done area are not entries in this array.

To move a section to another list, call move_section with its section_id and the destination list_id. The section is placed after that list's existing sections. All its tasks move with it, including completed and paused tasks and project or checklist children. The section keeps its title, description, and section_id. Calling it again with the same destination makes no further change.

Task IDs can change during a move between lists. Use query_tasks with the section's ID to read the current top-level members, then list_subtasks for their children. Include paused_filter:"include" and include_completed:true when you want all members.

Available Tools

You do not need to remember tool names during a chat. The tables below help you review Claude's actions or write your own MCP client. MCP and AppleScript use the same command names, arguments, response fields, and validation rules. For workflows in the Shortcuts app, see Shortcuts actions.

Read and Discovery

Tool	What it does
list_lists	List normal lists. Set include_archived:true to include archived lists.
list_sections	List saved sections in a normal list, in manual order. Requires list_id.
list_list_groups	List List Groups.
list_smart_lists	List saved Smart Lists.
list_tags	List tags and their paused state. Optionally filter by tag_group_id.
list_tag_groups	List tag groups.
list_locations	List task locations.
get_default_task_destination	Return the editable list used for new tasks by default, with its destination_id, list_id, and title.
get_task	Get one task, project, checklist, or sub-task by task_id.
query_tasks	Find tasks in a section, list, List Group, Smart List, or Focus view. With no target, use All. Supports search, date filters, sorting, and pagination.
list_subtasks	List a task's children. Supports paused_filter, sort, and include_completed.
selected_tasks	Return the tasks selected in the Mac app.

query_tasks accepts at most one of section_id, list_id, list_group_id, smart_list_id, or focus. The Focus values are all, today, starred, scheduled, and done. A List Group query uses the same dynamic task view as selecting that group in the sidebar. A section query returns its top-level tasks.

Use search for a literal phrase of 1 through 256 characters. It matches task titles, notes, tag names, and location names without regard to case or accents. It does not interpret query operators or Boolean expressions.

Filter dates with due_on_or_after, due_on_or_before, start_on_or_after, and start_on_or_before. These fields use yyyy-MM-dd and include both endpoints. A task without the relevant date does not match that filter.

Use sort to order results by title, due date, start date, priority, duration, creation date, modification date, or completion date. Use offset and limit to request a page of results; offset starts at zero and limit must be at least 1. Responses include item_count for the returned page and total_count for all matches. include_completed defaults to true; set it to false for unfinished tasks only.

Changes

Tool	What it does
create_section	Create a section at the end of a normal list. Requires list_id and title; accepts description.
move_section	Move a section and all its tasks to another list. Requires section_id and destination list_id.
reorder_sections	Set a list's section order. Requires list_id and all its section_ids in the desired order.
create_task	Create a task, project, checklist, or sub-task in a list, section, or parent task.
update_task	Change task fields, including section membership within the current list.
update_task_action	Set, replace, or clear the task action.
delete_task	Delete a task or a batch of tasks.
duplicate_task	Duplicate a task.
move_task	Move a task or batch to a list, section, or parent task.
complete_task	Mark a task or batch complete.
uncomplete_task	Mark a completed task or batch incomplete.
pause_tag	Pause a tag.
unpause_tag	Unpause a tag.

Complete, uncomplete, delete, and move accept either one task_id or up to 100 unique task_ids. 2Do validates the whole batch before applying it in order.

Delete, complete, and uncomplete also accept recursive, which defaults to true and includes children. Uncomplete accepts update_parent:true to update a completed parent too; this requires recursive:true.

Completing a recurring task advances it to its next occurrence. Repeating that command advances it again, so clients must not automatically retry recurring completion as though it made no further change.

Navigation

Tool	What it does
select_list	Select a normal list in the Mac app.
select_list_group	Select a List Group's dynamic task view.
select_smart_list	Select a saved Smart List.
select_focus	Select All, Today, Starred, Scheduled, or Done.
open_task	Open or focus a task in the Mac app.

Task Editing Support

Claude can create or update these task fields:

Field	Notes
title, notes	Task title and notes.
starred	Whether the task is starred.
task_type	normal, project, or checklist. When creating a task, this applies only to a top-level task.
section_id	Create or move a task into a section. In update_task, assign a top-level task to a section in the same list, or use null to clear membership.
due_date, due_time	Date as yyyy-MM-dd; time as HH:mm. Use null to clear.
start_date, start_time	Date as yyyy-MM-dd; time as HH:mm. Use null to clear.
duration_seconds	Estimated duration, from 0 through 2147483647 seconds.
priority	none, low, medium, or high.
tag_update	An operation (set, append, or remove) and tag_ids.
location_update	An operation (set, append, or remove) and location_ids.
alarms	Sound alarms. Omit to leave unchanged, send an empty array to clear, or send an array to replace. A task can have at most 10 total alarms.
recurrence	Daily, weekly, monthly, yearly, weekdays, or custom recurrence.
action	none, call, message, mail, visit, url, or google.

For an action alone, use update_task_action. For example, ask Claude to "change this task to call Sarah."

To create a project or checklist with children, pass subtasks to create_task with a list_id or section_id. Include 1 through 100 children, each with a non-empty title. Children do not have their own section membership.

Project children can have their own dates, priorities, tags, locations, alarms, recurrence, and actions. Child records cannot include section_id, other destinations, task_type, or nested subtasks. Checklist children inherit scheduling from their parent, so they cannot set due or start fields, duration, recurrence, or relative alarms. They can have absolute sound alarms.

Paused Tags

Pause a tag to hide matching tasks from normal task views; unpause it to show them again. pause_tag and unpause_tag take a tag_id and return the current tag record. Repeating either command leaves the tag in the requested state.

When reading tasks with query_tasks or list_subtasks, choose how to treat paused tasks:

paused_filter	Behavior
hide	Default. Hide tasks paused by tags.
include	Include paused and unpaused tasks.
only	Return only paused tasks.

For example, ask Claude to "include paused tasks when you review my Work list" or "show only tasks hidden by paused tags."

Dates, Alarms, and Recurrence

Use these formats when making tool calls directly:

• Dates: yyyy-MM-dd, such as 2026-10-20.
• Times: HH:mm, such as 09:30.
• Absolute alarm triggers: yyyy-MM-dd HH:mm, such as 2026-10-20 09:15.
• Relative alarm triggers: seconds, such as -900 for 15 minutes before. Offsets range from -63071999 through 63071999.

Dates and times are local values. Do not include timezone names, Z suffixes, or UTC offsets. Relative alarms require a due date or start date.

Recurrence also requires a due date or start date. To clear recurrence, send {"frequency":"none"}. A recurrence rule uses based_on (due_date or completion) and an end_rule; an after_count end rule accepts an occurrence_count from 1 through 99.

In task write requests, only the date and time fields above accept null, plus section_id in update_task. Omit other optional fields when you want to leave them unchanged.

See the AppleScript task reference for complete field rules and examples. MCP uses the same arguments as JSON objects instead of AppleScript records; use JSON null where an AppleScript example uses missing value.

Privacy and Security

The extension communicates with 2Do locally on your Mac. It returns requested data and command results to Claude, which processes that information under your Claude account's privacy terms. The extension does not add another network relay.

Automation uses the app's current unlocked session. Locked app data and locked password-protected lists remain unavailable. The API does not accept account passwords or sync credentials.

Troubleshooting

Claude says 2Do is not available

Open 2Do for Mac and keep it running while Claude uses its tools.

Claude cannot find a list, section, or tag

Ask Claude to list the relevant items first. list_sections needs the containing list's list_id. Claude should use the returned IDs in later calls, especially when several items share a name. Unlock any password-protected list you want Claude to access.

Claude reports an invalid argument or does not offer the section tools

Check that your app and extension support the command, then start a new chat to reload the tool definitions. Unknown argument names and unsupported values are rejected. Section tools require extension version 0.2.0 or later and a matching app build.

Claude reports "automation socket isn't available"

The extension could not connect to 2Do. Check these steps in order:

1. Confirm 2Do is running and includes MCP support.
2. Quit and reopen 2Do.
3. Quit and reopen Claude Desktop.

If the problem continues, 2Do's support logs show the socket path selected at launch. The protocol notes below include paths for local diagnostics.

Advanced Protocol Note

The native TwoDoMCPBridge executable runs as a local stdio MCP server. It negotiates MCP 2025-11-25 or 2025-06-18 through the initialize / notifications/initialized handshake. Its tool catalog stays fixed for the life of that process.

The bridge forwards calls to a Unix-domain socket in 2Do's App Group container. The app removes stale socket files at startup and creates its socket with 0600 permissions. The normal release path is:

~/Library/Group Containers/EKT6323JY3.com.guidedways/Automation/2do-mcp.sock

If the full path exceeds the Unix socket length limit, 2Do uses:

~/Library/Group Containers/EKT6323JY3.com.guidedways/mcp

Debug and internal builds use their matching App Group. For direct socket diagnostics, send one JSON object followed by a newline:

{"command":"query_tasks","arguments":{"paused_filter":"include","sort":{"field":"due_date","direction":"ascending"},"limit":10}}

A successful response contains result:

{"ok":true,"result":{"tasks":[],"item_count":0,"total_count":0}}

An error response contains a code and message:

{"ok":false,"error":{"code":"invalid_arguments","message":"Unknown argument 'id' for get_task."}}

Use the published MCP tools or AppleScript API for normal automation. The socket examples above describe the app connection, not MCP request envelopes.