Tweek MCP Server

Manage your Tweek tasks and calendars directly from AI assistants — Claude, ChatGPT, Cursor, and any MCP-compatible client. The server is hosted by Tweek; there is nothing to install or self-host.

Setup

Add the server to your MCP client configuration:

{
  "mcpServers": {
    "tweek": {
      "type": "http",
      "url": "https://tweek.so/mcp"
    }
  }
}

Client-specific locations:

On first use the client opens a browser window to sign in to Tweek and approve access.

Directories

Tweek is listed in these directories, so many clients can add it without pasting the URL:

Authentication

Tweek uses OAuth 2.0 with PKCE (Authorization Code flow). Your client registers itself automatically (Dynamic Client Registration, RFC 7591) and drives the flow — there is no client_id or API key to configure.

• Access tokens are JWTs, valid for 1 hour.
• Refresh tokens are valid for 30 days and rotate on use; refresh is handled automatically.
• Every request is scoped to your account. The assistant acts as you and never sees other users' data.

The assistant is granted these scopes on the consent screen:

This is the same authorization server as the REST API. See the API reference for the token, refresh, and introspection endpoints.

Tools

Read tools require the matching read scope; write tools require tasks:write. A failed call returns an error result with a message (see Errors) rather than aborting the connection. Results are JSON.

Every tool also returns machine-readable structuredContent, advertised as the tool's output schema in tools/list, so clients get typed results without parsing text. The examples below show each tool's shape; list tools wrap their array under a key (calendars, colors) because structured content must be an object.

list_calendars

List the calendars the user can access, including their lists. Needed to obtain a calendarId. No parameters.

[
  { "id": "CALENDAR_ID", "name": "My calendar", "isDefault": true, "lists": [] }
]

list_tasks

List tasks in a calendar. With both dateFrom and dateTo set (a window of at most 92 days), recurring tasks are automatically expanded into their per-day occurrences — the result matches what the user sees in the app for those dates and comes back in full, without pagination. Computed occurrences carry "virtual": true and an id like <taskId>_yyyyMMdd; passing such an id to update_task, complete_task or delete_task acts on that single occurrence. Without a date window the tool lists stored documents, paginated.

{ "data": [ /* task objects */ ], "pageSize": 100, "nextDocId": "TASK_ID" }

get_task

Fetch a single task.

create_task

Create a task. A task needs a placement to be visible — set date or listId. Field semantics match the REST task object.

{ "id": "GENERATED_TASK_ID" }

update_task

Apply partial updates to a task. Provide taskId plus at least one field to change. calendarId is fixed once a task exists. Sending checklist replaces the whole list — read the task first (get_task), then pass back every subtask you want to keep, each existing one with its id (new ones without), and drop the ones to delete.

For a recurring series, taskId may be a virtual-occurrence id from an expanded list_tasks (updates just that occurrence), and the optional updateType parameter picks the series mode: only_this, this_and_future or all_linked — the same choices the apps offer. With updateType set, only text, note, color, checklist, source, done and notifyAt may change. See the API reference.

{ "id": "TASK_ID", "updated": true }

complete_task

Mark a task done. Takes taskId. A shortcut for update_task with done: true. A virtual-occurrence id completes only that occurrence of a recurring series.

{ "id": "TASK_ID", "done": true }

delete_task

Delete a task. Takes taskId. For a recurring series, the optional updateType picks the mode: only_this removes a single occurrence (also what a virtual-occurrence id does by default), this_and_future ends the series from that occurrence on, all_linked permanently deletes every occurrence.

{ "id": "TASK_ID", "deleted": true }

Bulk tools

Act on many tasks in one call instead of looping a single-item tool. Each takes up to 50 items, runs them independently, and reports which succeeded and which failed — one bad item never aborts the batch. All require tasks:write.

{
  "succeeded": [ { "index": 0, "id": "TASK_ID" } ],
  "failed": [ { "index": 1, "error": "Not found" } ]
}

list_colors

List the user's custom colors. No parameters.

Plans & limits

Advanced fields — reminders (notifyAt), recurrence (freq, recurrence, dtStart) and subtasks — and custom colors require a paid plan. A tool call that uses them on a free account returns an Upgrade required error. Tool calls count against your account's API request quota — in an expanded list_tasks every returned occurrence counts as one read; see the API reference.

Errors

A tool call that fails returns an error result carrying a message, so the assistant can react without dropping the connection. Common cases:

Authorization and transport failures follow the standard OAuth error format documented in the API reference.