Projects

5 tools. Each one is also a REST route and a CLI command, from the same definition: the same input, the same output, the same errors.

Tool	What it does	Kind
`list_projects`	List the projects	Read · idempotent · no outside service
`archive_project`	Archive or restore a project	Write · destructive · no outside service
`create_project`	Create a project	Write · no outside service
`delete_project`	Delete an archived project for good	Write · destructive · idempotent · no outside service
`update_project`	Update a project	Write · idempotent · no outside service

list_projects

List the projects. Returns active and completed projects in manual order, with their task counts. Archived projects are excluded unless includeArchived=true.


Kind	Read · idempotent · no outside service
Auth	Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`)
REST	`GET https://api.doers.sh/v2/projects`
CLI	`doers projects list`
Touches	`projects`, `tasks`
Operation	`listProjects`

Input

Field	Type	Required	Default	Allowed values	Description
`areaId` (query)	string	no		UUID	Identifier of a row.
`status` (query)	string	no		`active`, `done`	No description in the registry.
`includeArchived` (query)	boolean	no	`false`		No description in the registry.
`workspaceId` (query)	string	no		UUID	The workspace to read within; the personal one by default (T-D11).

Output

Output fields

Field	Type	Allowed values	Description
`projects`	object[]
`projects[].id`	string
`projects[].name`	string
`projects[].areaId`	string \| null
`projects[].status`	string	`active`, `done`, `archived`
`projects[].deadline`	string \| null
`projects[].notes`	string
`projects[].order`	number		Manual position. Fractional values are valid; lower sorts first.
`projects[].accessRole`	string (optional)	`owner`, `editor`, `commenter`, `reader`	Your effective role on this project.
`projects[].openTaskCount`	integer	-9007199254740991 to 9007199254740991
`projects[].doneTaskCount`	integer	-9007199254740991 to 9007199254740991

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_projects",
    "arguments": {
      "areaId": "4a91ee5f-0106-42b3-8c11-c168352f0abf",
      "status": "active"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "- [244210e4-8437-4655-8980-a70249a99369] Acme · 3/6"
      }
    ],
    "structuredContent": {
      "projects": [
        {
          "id": "244210e4-8437-4655-8980-a70249a99369",
          "name": "Acme",
          "areaId": "4a91ee5f-0106-42b3-8c11-c168352f0abf",
          "status": "active",
          "deadline": "2026-09-22",
          "notes": "Notes for the Acme launch.",
          "order": 0,
          "accessRole": "owner",
          "openTaskCount": 3,
          "doneTaskCount": 3
        }
      ]
    }
  }
}

doers projects list --area-id 4a91ee5f-0106-42b3-8c11-c168352f0abf --status active

archive_project

Archive or restore a project. Archiving is reversible and cascades to the project’s open tasks. restore: true makes the project active again; its tasks are not unarchived automatically, matching the app.


Kind	Write · destructive · no outside service
Auth	Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`)
REST	`POST https://api.doers.sh/v2/projects/{projectId}/archive`
CLI	`doers projects archive`
Touches	`projects`, `tasks`
Operation	`archiveProject`

Input

Field	Type	Required	Default	Allowed values	Description
`projectId` (path)	string	yes		UUID	Identifier of a row.
`restore`	boolean	no	`false`		No description in the registry.

Output

Output fields

Field	Type	Allowed values	Description
`project`	object
`project.id`	string
`project.name`	string
`project.areaId`	string \| null
`project.status`	string	`active`, `done`, `archived`
`project.deadline`	string \| null
`project.notes`	string
`project.order`	number		Manual position. Fractional values are valid; lower sorts first.
`project.accessRole`	string (optional)	`owner`, `editor`, `commenter`, `reader`	Your effective role on this project.
`archivedTasks`	integer	-9007199254740991 to 9007199254740991

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "archive_project",
    "arguments": {
      "projectId": "244210e4-8437-4655-8980-a70249a99369",
      "restore": false
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "OK: project restored."
      }
    ],
    "structuredContent": {
      "project": {
        "id": "244210e4-8437-4655-8980-a70249a99369",
        "name": "Acme",
        "areaId": "4a91ee5f-0106-42b3-8c11-c168352f0abf",
        "status": "active",
        "deadline": "2026-09-22",
        "notes": "Notes for the Acme launch.",
        "order": 0,
        "accessRole": "owner"
      },
      "archivedTasks": 3
    }
  }
}

doers projects archive 244210e4-8437-4655-8980-a70249a99369 --restore false

create_project

Create a project. Creates an active project, optionally attached to an area and with a deadline. A project with no area is filed under “No area”.


Kind	Write · no outside service
Auth	Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`)
REST	`POST https://api.doers.sh/v2/projects`
CLI	`doers projects create`
Touches	`projects`, `tasks`
Operation	`createProject`

Input

Field	Type	Required	Allowed values	Description
`name`	string	yes	1 to 200 characters	No description in the registry.
`areaId`	string \| null	no	UUID	No description in the registry.
`workspaceId`	string	no	UUID	Where to file it: the personal workspace by default, or a team workspace the caller sits in.
`deadline`	string \| null	no	`YYYY-MM-DD`	No description in the registry.
`notes`	string	no	0 to 10000 characters	Markdown: bold, italic, headings, lists, quotes, rules, links, inline code, tables and checkboxes. Do not use code blocks (```) or images: the app’s editor does not support them and truncates the display from that point on.

Output

Output fields

Field	Type	Allowed values	Description
`project`	object
`project.id`	string
`project.name`	string
`project.areaId`	string \| null
`project.status`	string	`active`, `done`, `archived`
`project.deadline`	string \| null
`project.notes`	string
`project.order`	number		Manual position. Fractional values are valid; lower sorts first.
`project.accessRole`	string (optional)	`owner`, `editor`, `commenter`, `reader`	Your effective role on this project.

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_project",
    "arguments": {
      "name": "Acme",
      "areaId": "4a91ee5f-0106-42b3-8c11-c168352f0abf",
      "deadline": "2026-09-22"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "OK: project “Acme” created [244210e4-8437-4655-8980-a70249a99369]."
      }
    ],
    "structuredContent": {
      "project": {
        "id": "244210e4-8437-4655-8980-a70249a99369",
        "name": "Acme",
        "areaId": "4a91ee5f-0106-42b3-8c11-c168352f0abf",
        "status": "active",
        "deadline": "2026-09-22",
        "notes": "Notes for the Acme launch.",
        "order": 0,
        "accessRole": "owner"
      }
    }
  }
}

doers projects create Acme --area-id 4a91ee5f-0106-42b3-8c11-c168352f0abf --deadline 2026-09-22

delete_project

Delete an archived project for good. Removes a project permanently. The project must already be archived: the irreversible step is deliberately reachable only from the reversible one. Its tasks are detached, never deleted: they lose their project and stay.


Kind	Write · destructive · idempotent · no outside service
Auth	Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`)
REST	`DELETE https://api.doers.sh/v2/projects/{projectId}`
CLI	`doers projects delete`
Touches	`projects`, `tasks`
Operation	`deleteProject`

Input

Field	Type	Required	Default	Allowed values	Description
`projectId` (path)	string	yes		UUID	Identifier of a row.

Output

Output fields

Field	Type	Allowed values	Description
`projectId`	string
`detachedTasks`	integer	-9007199254740991 to 9007199254740991

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "delete_project",
    "arguments": {
      "projectId": "244210e4-8437-4655-8980-a70249a99369"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "OK: project deleted. 3 task(s) kept, without a project."
      }
    ],
    "structuredContent": {
      "projectId": "244210e4-8437-4655-8980-a70249a99369",
      "detachedTasks": 3
    }
  }
}

doers projects delete 244210e4-8437-4655-8980-a70249a99369

update_project

Update a project. Partial patch: name, area, deadline, status or notes. Passing status: "done" marks the project complete without touching its tasks.


Kind	Write · idempotent · no outside service
Auth	Bearer token: a personal API token (`pc_…`) or an OAuth access token (`pcat_…`)
REST	`PATCH https://api.doers.sh/v2/projects/{projectId}`
CLI	`doers projects update`
Touches	`projects`, `tasks`
Operation	`updateProject`

Input

Field	Type	Required	Allowed values	Description
`projectId` (path)	string	yes	UUID	Identifier of a row.
`name`	string	no	1 to 200 characters	No description in the registry.
`areaId`	string \| null	no	UUID	No description in the registry.
`deadline`	string \| null	no	`YYYY-MM-DD`	No description in the registry.
`status`	string	no	`active`, `done`	No description in the registry.
`notes`	string	no	0 to 10000 characters	Markdown: bold, italic, headings, lists, quotes, rules, links, inline code, tables and checkboxes. Do not use code blocks (```) or images: the app’s editor does not support them and truncates the display from that point on.
`order`	number	no		Manual position. Fractional values are valid; lower sorts first.

Output

Output fields

Field	Type	Allowed values	Description
`project`	object
`project.id`	string
`project.name`	string
`project.areaId`	string \| null
`project.status`	string	`active`, `done`, `archived`
`project.deadline`	string \| null
`project.notes`	string
`project.order`	number		Manual position. Fractional values are valid; lower sorts first.
`project.accessRole`	string (optional)	`owner`, `editor`, `commenter`, `reader`	Your effective role on this project.

Example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "update_project",
    "arguments": {
      "projectId": "244210e4-8437-4655-8980-a70249a99369",
      "name": "Acme",
      "areaId": "4a91ee5f-0106-42b3-8c11-c168352f0abf"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "OK: project “Acme” updated."
      }
    ],
    "structuredContent": {
      "project": {
        "id": "244210e4-8437-4655-8980-a70249a99369",
        "name": "Acme",
        "areaId": "4a91ee5f-0106-42b3-8c11-c168352f0abf",
        "status": "active",
        "deadline": "2026-09-22",
        "notes": "Notes for the Acme launch.",
        "order": 0,
        "accessRole": "owner"
      }
    }
  }
}

doers projects update 244210e4-8437-4655-8980-a70249a99369 --name Acme --area-id 4a91ee5f-0106-42b3-8c11-c168352f0abf

MCP server

Tool reference

list_projects

Input

Output

Example

archive_project

Input

Output

Example

create_project

Input

Output

Example

delete_project

Input

Output

Example

update_project

Input

Output

Example

​list_projects

​Input

​Output

​Example

​archive_project

​Input

​Output

​Example

​create_project

​Input

​Output

​Example

​delete_project

​Input

​Output

​Example

​update_project

​Input

​Output

​Example

list_projects

Input

Output

Example

archive_project

Input

Output

Example

create_project

Input

Output

Example

delete_project

Input

Output

Example

update_project

Input

Output

Example