Sunsama MCP server Let your AI agent plan your day in Sunsama.

ToolWhat it doesAccess

• list_tasks Lists the tasks planned for one day, with channel, planned time and status. read

  Returns each task with its ID, title, channel, planned and actual minutes, whether it has a working session and its subtask count. Tasks come in the order Sunsama shows them for the day. It also returns the day's total planned minutes, so your agent can compare the workload with your threshold.

  MCP callsunsama_read → list_tasks

  REST endpointGET https://cotlet.dev/api/v1/sunsama/tasks

  Parameters

  Parameters: list_tasks

  Name	Type	Description
  date string	string	The day to read. Date as YYYY-MM-DD. Defaults to today.
  channel string	string	Only tasks in this channel, by name.
  status string	string	Filter by status. One of: open, completed, all. Defaults to all.

  Example response

  {
    "date": "2026-11-06",
    "planned_minutes_total": 135,
    "tasks": [
      {
        "task_id": "task_8f31c2",
        "title": "Draft proposal for Acme",
        "channel": "Clients",
        "planned_minutes": 60,
        "actual_minutes": null,
        "status": "open",
        "has_working_session": true,
        "subtasks": 2
      },
      {
        "task_id": "task_8f31c9",
        "title": "Review onboarding emails",
        "channel": "Marketing",
        "planned_minutes": 45,
        "actual_minutes": null,
        "status": "open",
        "has_working_session": false,
        "subtasks": 0
      },
      {
        "task_id": "task_8f31d4",
        "title": "Send weekly invoices",
        "channel": "Admin",
        "planned_minutes": 30,
        "actual_minutes": 25,
        "status": "completed",
        "has_working_session": false,
        "subtasks": 0
      }
    ]
  }

• get_task Returns one task with its notes, subtasks, times and objective. read

  Returns the full task card: notes, every subtask with its status, planned and actual time as totals across all days the task appears on, its channel, its repeat setting and the objective it is aligned with. Use it before an update so your agent changes only what is needed.

  MCP callsunsama_read → get_task

  REST endpointGET https://cotlet.dev/api/v1/sunsama/tasks/{task_id}

  Parameters

  Parameters: get_task

  Name	Type	Description
  task_id string required	string	Task ID from list_tasks or list_backlog_tasks.

  Example input

  {
    "task_id": "task_8c41d2"
  }

  Example response

  {
    "task_id": "task_8f31c2",
    "title": "Draft proposal for Acme",
    "channel": "Clients",
    "notes": "Use the Q4 template.",
    "planned_minutes": 60,
    "actual_minutes": null,
    "status": "open",
    "repeat": null,
    "objective": "Close the Acme deal",
    "subtasks": [
      {
        "subtask_id": "sub_01",
        "title": "Outline scope",
        "status": "completed"
      },
      {
        "subtask_id": "sub_02",
        "title": "Price the options",
        "status": "open"
      }
    ]
  }

• create_task Creates a task on a day or in the backlog. write

  Returns the new task with its ID. Without date the task lands in the backlog. A channel that does not exist fails at once, so your agent never files a task under a wrong one. Set the channel, notes and estimate here when the task will repeat later, because every instance copies them. The task is private to your account and is deleted in Sunsama in one click, so the call does not wait for your OK.

  MCP callsunsama_write → create_task

  REST endpointPOST https://cotlet.dev/api/v1/sunsama/tasks

  Parameters

  Parameters: create_task

  Name	Type	Description
  title string required	string	Task name.
  date string	string	Day to plan it on. Date as YYYY-MM-DD. Leave out to put it in the backlog.
  channel string	string	Channel name from list_channels.
  planned_minutes integer	integer	Time estimate in minutes.
  notes string	string	Task notes, plain text.

  Example input

  {
    "title": "title"
  }

  Example response

  {
    "task_id": "task_9b12e0",
    "title": "Call the accountant",
    "date": "2026-11-09",
    "channel": "Admin",
    "planned_minutes": 30,
    "status": "open"
  }

• update_task Changes the title, notes, channel or planned time of a task. write

  Returns the task as it is now. Only the fields you send change. When the task already has a working session on the calendar, its planned time follows the session, so change the estimate with timebox_task. It reaches no one else and is undone with one call, so it does not wait for your OK.

  MCP callsunsama_write → update_task

  REST endpointPATCH https://cotlet.dev/api/v1/sunsama/tasks/{task_id}

  Parameters

  Parameters: update_task

  Name	Type	Description
  task_id string required	string	Task ID from list_tasks or list_backlog_tasks.
  title string	string	New task name.
  notes string	string	New notes. Replaces the old notes.
  channel string	string	Channel name from list_channels.
  planned_minutes integer	integer	New time estimate in minutes.

  Example input

  {
    "task_id": "task_8c41d2"
  }

  Example response

  {
    "task_id": "task_8f31c9",
    "title": "Review onboarding emails",
    "channel": "Marketing",
    "planned_minutes": 30,
    "status": "open"
  }

• add_subtask Adds a subtask to a task. write

  Returns the subtask and the new subtask count of the task. It reaches no one else and is undone with one call, so it does not wait for your OK.

  MCP callsunsama_write → add_subtask

  REST endpointPOST https://cotlet.dev/api/v1/sunsama/tasks/{task_id}/subtasks

  Parameters

  Parameters: add_subtask

  Name	Type	Description
  task_id string required	string	Task ID from list_tasks or list_backlog_tasks.
  title string required	string	Subtask name.

  Example input

  {
    "task_id": "task_8c41d2",
    "title": "title"
  }

  Example response

  {
    "subtask_id": "sub_03",
    "task_id": "task_8f31c2",
    "title": "Send the draft to Maya",
    "status": "open",
    "subtasks_total": 3
  }

• complete_task Marks a task as complete, or reopens it. write

  Returns the task with its new status. Sunsama can count the planned time as actual time for a task finished without logged time, but only when that setting is on in your account, so log time first with set_actual_time. It reaches no one else and is undone with one call, so it does not wait for your OK.

  MCP callsunsama_write → complete_task

  REST endpointPOST https://cotlet.dev/api/v1/sunsama/tasks/{task_id}/complete

  Parameters

  Parameters: complete_task

  Name	Type	Description
  task_id string required	string	Task ID from list_tasks or list_backlog_tasks.
  completed boolean	boolean	true to complete, false to reopen. Defaults to true.

  Example input

  {
    "task_id": "task_8c41d2"
  }

  Example response

  {
    "task_id": "task_8f31d4",
    "status": "completed",
    "planned_minutes": 30,
    "actual_minutes": 25
  }

• move_task Moves a task to another day or into the backlog. write

  Returns the task with its new day. Moving a task to another day removes its working session, so timebox it again. Scheduling a backlog task to a day clears its folder. It reaches no one else and is undone with one call, so it does not wait for your OK.

  MCP callsunsama_write → move_task

  REST endpointPOST https://cotlet.dev/api/v1/sunsama/tasks/{task_id}/move

  Parameters

  Parameters: move_task

  Name	Type	Description
  task_id string required	string	Task ID from list_tasks or list_backlog_tasks.
  date string	string	Day to move it to. Date as YYYY-MM-DD. Leave out to move it to the backlog.

  Example input

  {
    "task_id": "task_8c41d2"
  }

  Example response

  {
    "task_id": "task_7a20b1",
    "date": "2026-11-06",
    "in_backlog": false,
    "has_working_session": false
  }

ToolWhat it doesAccess

• list_backlog_tasks Lists the tasks in your someday backlog. read

  Returns the tasks you stored for someday, with channel, planned minutes and the bucket or folder they sit in. When the list is longer than one page, the response carries next_cursor; call again with it until it is empty.

  MCP callsunsama_read → list_backlog_tasks

  REST endpointGET https://cotlet.dev/api/v1/sunsama/backlog-tasks

  Parameters

  Parameters: list_backlog_tasks

  Name	Type	Description
  channel string	string	Only tasks in this channel, by name.
  cursor string	string	Next page cursor from the previous call.

  Example response

  {
    "tasks": [
      {
        "task_id": "task_7a20b1",
        "title": "Update portfolio page",
        "channel": "Marketing",
        "planned_minutes": 90,
        "bucket": "Someday"
      },
      {
        "task_id": "task_7a20c5",
        "title": "Research invoicing tools",
        "channel": "Admin",
        "planned_minutes": 45,
        "bucket": "Someday"
      }
    ],
    "next_cursor": null
  }

• list_channels Lists your channels and the contexts they belong to. read

  Returns the name of every enabled channel and its context. Channels categorize tasks, events and objectives. Your agent reads this before create_task so it assigns a channel that exists.

  MCP callsunsama_read → list_channels

  REST endpointGET https://cotlet.dev/api/v1/sunsama/channels

  Parameters

  No parameters.

  Example response

  {
    "channels": [
      {
        "name": "Clients",
        "context": "Work"
      },
      {
        "name": "Marketing",
        "context": "Work"
      },
      {
        "name": "Admin",
        "context": "Work"
      },
      {
        "name": "Personal",
        "context": "Life"
      }
    ]
  }

ToolWhat it doesAccess

• timebox_task Adds a working session for a task to the calendar. write

  Returns the session with its start, end and the task's new planned time. A task can have sessions on several days and then shows on each of them. It reaches no one else and is undone with one call, so it does not wait for your OK.

  MCP callsunsama_write → timebox_task

  REST endpointPOST https://cotlet.dev/api/v1/sunsama/tasks/{task_id}/timebox

  Parameters

  Parameters: timebox_task

  Name	Type	Description
  task_id string required	string	Task ID from list_tasks or list_backlog_tasks.
  date string required	string	Day of the session. Date as YYYY-MM-DD.
  start_time string required	string	Start in 24-hour HH:MM, in your Sunsama time zone.
  duration_minutes integer required	integer	Length of the session in minutes. It becomes the task's planned time.

  Example input

  {
    "task_id": "task_8f31c9",
    "date": "2026-11-06",
    "start_time": "10:00",
    "duration_minutes": 45
  }

  Example response

  {
    "task_id": "task_8f31c9",
    "date": "2026-11-06",
    "start_time": "10:00",
    "end_time": "10:45",
    "planned_minutes": 45
  }

• set_actual_time Records how long a task actually took. write

  Returns the task with planned and actual minutes side by side. The value replaces any earlier actual time on the task. It reaches no one else and is undone with one call, so it does not wait for your OK.

  MCP callsunsama_write → set_actual_time

  REST endpointPUT https://cotlet.dev/api/v1/sunsama/tasks/{task_id}/actual-time

  Parameters

  Parameters: set_actual_time

  Name	Type	Description
  task_id string required	string	Task ID from list_tasks or list_backlog_tasks.
  actual_minutes integer required	integer	Time spent in minutes.

  Example input

  {
    "task_id": "task_8c41d2",
    "actual_minutes": 1
  }

  Example response

  {
    "task_id": "task_8f31d4",
    "planned_minutes": 30,
    "actual_minutes": 25
  }

ToolWhat it doesAccess

• set_task_repeat Makes a task repeat on weekdays or on chosen days of the week. write

  Returns the repeat setting. Sunsama copies the task's channel, subtasks, notes and estimate into every future instance, so set them first. Recurring tasks roll over until they collide with another instance of the same task. It reaches no one else and is undone with one call, so it does not wait for your OK.

  MCP callsunsama_write → set_task_repeat

  REST endpointPUT https://cotlet.dev/api/v1/sunsama/tasks/{task_id}/repeat

  Parameters

  Parameters: set_task_repeat

  Name	Type	Description
  task_id string required	string	Task ID from list_tasks or list_backlog_tasks.
  repeat string required	string	One of: weekdays, weekly, none. none stops the repeat.
  days array	array	For weekly: the days, as mon, tue, wed, thu, fri, sat, sun.
  start_time string	string	Optional start in 24-hour HH:MM. It guides auto-scheduling and the order of your list.

  Example input

  {
    "task_id": "task_8c41d2",
    "repeat": "repeat"
  }

  Example response

  {
    "task_id": "task_9b12e1",
    "repeat": "weekly",
    "days": [
      "fri"
    ],
    "start_time": "14:00"
  }

• list_objectives Lists the weekly objectives of one week with the tasks aligned to each. read

  Returns each objective with its channel and the tasks aligned with it, each with its day and status. An objective extended from last week shows in both weeks.

  MCP callsunsama_read → list_objectives

  REST endpointGET https://cotlet.dev/api/v1/sunsama/objectives

  Parameters

  Parameters: list_objectives

  Name	Type	Description
  week_of string	string	Any day inside the week to read. Date as YYYY-MM-DD. Defaults to the current week.

  Example response

  {
    "week_of": "2026-11-02",
    "objectives": [
      {
        "objective_id": "obj_41",
        "title": "Close the Acme deal",
        "channel": "Clients",
        "tasks": [
          {
            "task_id": "task_8f31c2",
            "day": "2026-11-06",
            "status": "open"
          }
        ]
      },
      {
        "objective_id": "obj_42",
        "title": "Publish the autumn newsletter",
        "channel": "Marketing",
        "tasks": []
      }
    ]
  }

• align_task_with_objective Links a task to a weekly objective. write

  Returns the task with its objective. A task without a channel takes the objective's channel, and a task that has one keeps it. It reaches no one else and is undone with one call, so it does not wait for your OK.

  MCP callsunsama_write → align_task_with_objective

  REST endpointPOST https://cotlet.dev/api/v1/sunsama/objectives/{objective_id}/tasks/{task_id}/with-objective/align

  Parameters

  Parameters: align_task_with_objective

  Name	Type	Description
  task_id string required	string	Task ID from list_tasks or list_backlog_tasks.
  objective_id string required	string	Objective ID from list_objectives.

  Example input

  {
    "task_id": "task_8c41d2",
    "objective_id": "objective_8c41d2"
  }

  Example response

  {
    "task_id": "task_9b12e0",
    "objective_id": "obj_41",
    "objective": "Close the Acme deal",
    "channel": "Admin"
  }