REST API 与 MCP Server 文档 — Claude Code 集成

− Claude Code 集成

TaskLeef includes a Model Context Protocol (MCP) server that allows AI assistants like Claude Code to manage your todos, boards, and Kanban workflows directly from the command line.

快速开始

Get your API key from Settings → API Keys

Add the MCP server to Claude Code:

claude mcp add --transport http taskleef https://taskleef.com/mcp/messages -H "X-API-Key: YOUR_API_KEY"

重启 Claude Code
Verify it's working:
```
claude mcp list
```
You should see taskleef with a green checkmark.

备选方案：手动配置

Add directly to ~/.claude.json:

{
  "mcpServers": {
    "taskleef": {
      "type": "http",
      "url": "https://taskleef.com/mcp/messages",
      "headers": {
        "X-API-Key": "your-api-key-here"
      }
    }
  }
}

可用工具

The MCP server provides 40 tools across 7 domains:

待办事项7 个工具

看板5 个工具

列6 个工具

卡片5 个工具

成员5 个工具

标签7 个工具

评论5 个工具

用法示例

配置完成后，您可以用自然语言让 Claude 管理任务：

“显示我本周的待办事项”
“创建一个待办事项，在周五前审阅季度报告 [work]”
“将身份验证任务移动到 Sprint 看板的进行中”
“给 API 重构任务添加一条评论，说明我已开始审阅”
“为我所有的会议待办事项打上 ‘meetings’ 标签”
“创建一个名为 ‘Q2 Planning’ 的新看板”

Claude Desktop

对于 Claude Desktop，请添加到您的 MCP 设置文件中：

{
  "mcpServers": {
    "taskleef": {
      "transport": {
        "type": "sse",
        "url": "https://taskleef.com/mcp/sse",
        "headers": {
          "X-API-Key": "your-api-key-here"
        }
      }
    }
  }
}

− Claude.ai 与 Claude CoWork

You can also use TaskLeef as a custom connector in Claude.ai (web), Claude Desktop, and Claude CoWork. The connector uses standard OAuth 2.1, so each user signs in with their own TaskLeef account — no shared API keys.

设置

In Claude, open Settings → Connectors → Add custom connector (Claude.ai web) or Settings → Connectors (Claude Desktop / CoWork).
Enter the server URL:
```
https://taskleef.com/mcp/messages
```
Leave the optional OAuth Client ID and Client Secret fields blank — TaskLeef supports Dynamic Client Registration (RFC 7591), so Claude provisions a client automatically.
Click Add. Claude opens a browser tab to taskleef.com and asks you to sign in.
Sign in (email/password or SSO via GitHub, Google, Microsoft, or Apple), click Authorize, and you're done. Claude redirects back automatically.

Claude 能做什么

Once connected, Claude has access to all 40 MCP tools across todos, boards, columns, cards, members, tags, and comments. Try asking:

“我这周有哪些任务要做？”
“创建一个名为 ‘Q3 launch’ 的看板，并添加 Backlog、Doing 和 Done 这几列。”
“将我的 Sprint 看板上的 API 重构任务移动到进行中。”
“为标题中包含 ‘meeting’ 的每个待办事项打上 meetings 标签。”
“总结我收件箱中未完成的待办事项，并为明天提出优先级建议。”
“给部署工单添加一条评论，说明我午饭后会接手。”

工具安全性标注

连接器公开的每个工具都为 Claude 进行了标注，以便它在执行破坏性操作前向您发出警告：

只读13 个工具

修改20 个工具

破坏性7 个工具

Destructive tools (delete todo, delete board, delete column, delete card, remove member, delete tag, delete comment) are flagged with destructiveHint: true, so Claude will ask for confirmation before running them.

Claude Code 与 Claude.ai / CoWork 对比

功能	Claude Code (CLI)	Claude.ai / CoWork
设置	在 CLI 中使用 API 密钥	在浏览器中使用 OAuth
认证	Static `X-API-Key` header	每位用户的 OAuth 2.1 访问令牌
运行位置	本地终端	Claude.ai / CoWork 云端
令牌生命周期	在设置中手动轮换	自动刷新，可在设置中撤销
多用户	每台机器一个密钥	每位用户单独登录

撤销访问权限

要断开某个 Claude 会话与 TaskLeef 的连接，请在 Claude 中移除该连接器。刷新令牌每次使用后都会轮换，因此已关闭会话中的过期令牌无法被重放。

隐私

The OAuth flow happens entirely between your browser, taskleef.com, and Claude. Your password is never sent to Claude. The access token Claude receives is scoped to MCP only and bound to the audience https://taskleef.com/mcp — it can't be replayed against any other API.

− 身份验证

该 API 支持两种身份验证方式：

1. API 密钥身份验证（推荐）

Generate an API key from your Settings page and include it in the X-API-Key header:

curl -H "X-API-Key: your-api-key" \
  https://taskleef.com/api/todos

2. JWT Bearer 令牌

对于基于浏览器的应用，请通过登录端点进行身份验证：

curl -X POST https://taskleef.com/api/login \
  -H "Content-Type: application/json" \
  -d '{"username": "your-username", "password": "your-password"}'

然后在后续请求中包含该令牌：

curl -H "Authorization: Bearer your-jwt-token" \
  https://taskleef.com/api/todos

− 待办事项

GET/api/todos

获取已认证用户的所有待办事项。

curl -H "X-API-Key: your-api-key" \
  https://taskleef.com/api/todos

GET/api/todos/{id}

按 ID 获取特定待办事项。

GET/api/inbox

获取未分配到任何项目的待办事项。

POST/api/todos

创建新的待办事项。

curl -X POST -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"title": "Buy groceries", "description": "Milk, eggs, bread"}' \
  https://taskleef.com/api/todos

请求体

字段	类型	必填	说明
title	string	Yes	Todo title
description	string	No	Detailed description
dueDate	ISO 8601	No	Due date/time
priority	string	No	Low, Medium, High, or Urgent
projectId	UUID	No	Assign to a project

PUT/api/todos/{id}

更新现有待办事项。

PATCH/api/todos/{id}/complete

切换待办事项的完成状态。

curl -X PATCH -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"isCompleted": true}' \
  https://taskleef.com/api/todos/{id}/complete

DELETE/api/todos/{id}

删除待办事项。

POST/api/todos/{parentId}/subtasks

在父待办事项下创建子任务。

curl -X POST -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"title": "Subtask title"}' \
  https://taskleef.com/api/todos/{parentId}/subtasks

− 项目

GET/api/projects

列出已认证用户的所有项目。

POST/api/projects

创建新项目。

curl -X POST -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"title": "Work Tasks", "description": "Tasks for work"}' \
  https://taskleef.com/api/projects

GET/api/projects/{id}

获取特定项目及其待办事项。

PUT/api/projects/{id}

更新项目。

DELETE/api/projects/{id}

删除项目（待办事项将移至收件箱）。

− Kanban 看板

GET/api/boards

列出用户有权访问的所有看板。

POST/api/boards

创建新看板。

curl -X POST -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"title": "Sprint Board", "projectId": "project-uuid"}' \
  https://taskleef.com/api/boards

GET/api/boards/{id}

获取特定看板。

GET/api/boards/{boardId}/columns

获取某个看板的所有列。

GET/api/boards/{boardId}/todos

获取在此看板上拥有卡片的所有待办事项。

− 列

POST/api/boards/{boardId}/columns

在看板上创建新列。

curl -X POST -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"title": "In Progress", "wipLimit": 3}' \
  https://taskleef.com/api/boards/{boardId}/columns

PUT/api/columns/{id}

更新列（标题、WIP 限制、完成标准）。

GET/api/columns/{columnId}/cards

获取某一列中的所有卡片。

DELETE/api/columns/{id}

删除列。

− 卡片

卡片表示 Kanban 看板上的待办事项。一个待办事项可以在多个看板上拥有卡片。

POST/api/columns/{columnId}/cards

在某一列中为待办事项创建卡片。

curl -X POST -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"todoId": "todo-uuid"}' \
  https://taskleef.com/api/columns/{columnId}/cards

PUT/api/cards/{id}

更新卡片（移动到不同的列或子列）。

# Move card to a different column
curl -X PUT -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"columnId": "new-column-uuid", "subColumn": "Inbox"}' \
  https://taskleef.com/api/cards/{id}

# Move card to Done subColumn
curl -X PUT -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"subColumn": "Done"}' \
  https://taskleef.com/api/cards/{id}

子列取值

Inbox - Active items in the column
Done - Completed items within the column
Blocked - Items waiting on external dependencies

DELETE/api/cards/{id}

从看板中移除卡片（不会删除待办事项）。

− 标签

GET/api/tags

列出已认证用户的所有标签。

POST/api/tags

创建新标签。

curl -X POST -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"name": "urgent"}' \
  https://taskleef.com/api/tags

PUT/api/tags/{id}

更新标签。

DELETE/api/tags/{id}

删除标签。

− 评论

GET/api/todos/{todoId}/comments

获取某个待办事项上的所有评论。

POST/api/todos/{todoId}/comments

为待办事项添加评论。

curl -X POST -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"text": "This is my comment"}' \
  https://taskleef.com/api/todos/{todoId}/comments

PUT/api/comments/{id}

更新评论。

DELETE/api/comments/{id}

删除评论。

− 响应格式

成功响应

成功的请求会返回包含所请求数据的 JSON：

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Buy groceries",
  "description": "Milk, eggs, bread",
  "isCompleted": false,
  "createdAt": "2024-01-15T10:30:00Z"
}

错误响应

错误会返回相应的 HTTP 状态码：

400 - Bad Request (invalid input)
401 - Unauthorized (missing or invalid authentication)
403 - Forbidden (insufficient permissions)
404 - Not Found
500 - Internal Server Error