Kelvia

Kelvia MCP — 面向编码 Agent 的任务管理器

Kelvia 是一款供人和编码 Agent 共用的任务管理器。一个具体用途是：将未完成的任务从 Claude Code 移交给 Codex。指南提供了一种可复制的仓库文件移交方式，无需 Kelvia 即可使用，随后会介绍何时适合使用共享任务。通过 Model Context Protocol，Agent 可以创建和更新任务、在看板上推进工作、发表评论、记录时间、运行阶段并规划每日安排。所有更改都会在与用户相同的界面中显示，并注明执行者。

该服务提供 58 个工具，可与 Claude Code、Codex、Cursor 及其他 MCP 客户端配合使用。托管端点使用 OAuth，因此在推荐配置中无需粘贴 API 令牌。本地 stdio 模式可用于 CI 和不支持远程 MCP 的客户端。

免费试用 · MCP 文档 · 托管端点

一条命令即可连接

客户端	命令
Claude Code	claude mcp add --transport http --scope user kelvia https://mcp.kelvia.app/mcp
Codex	codex mcp add kelvia --url https://mcp.kelvia.app/mcp
Cursor	在 设置 → 工具与 MCP 中添加 https://mcp.kelvia.app/mcp

首次连接时，浏览器会打开 Kelvia 以批准 OAuth。连接完成后，向客户端提问：List my Kelvia boards.

为什么选择 Kelvia MCP

• 覆盖完整工作流 — 创建和分类任务、在看板上推进工作、记录时间、运行阶段并规划每日安排。它不只是一个只读桥接工具。
• 可控的写入权限 — Agent 密钥具有读取／创建／编辑／删除权限范围，并与 Agent 在每个看板上的角色权限取交集。
• Agent 活动清晰可见 — 更改、评论和工作日志会显示在 Kelvia 中；用户可在应用中撤销受支持的任务更改。
• 按需加载 — 工具集允许客户端仅发布产品的一部分，而不是全部 58 个工具。
• 现代远程身份验证 — 使用 Streamable HTTP 搭配 OAuth 2.1 + PKCE；如果需要指定 Agent 身份，也可以使用 Bearer 令牌。
• 按需使用本地模式 — 对于不支持远程 MCP 的客户端、CI，或需要将密钥保存在单台设备上的场景，可使用 stdio。

查看实际效果

从客户端一侧来看——只需一个提示词，Agent 就会读取看板、判断哪些内容重要、创建后续任务，并对阻塞项发表评论：

_{这是针对 mcp.kelvia.app 的真实会话，根据其记录排版。 create_task 确实创建了 #17，add_task_comment 也确实评论了 #9——本节其余内容展示的正是这些操作。}

再从产品一侧来看。以下所有内容均由 Agent 通过此服务创建——看板、任务、讨论和工时记录。

观看同一运行过程的视频

Agent 所做的每项更改都会标明归属，并可筛选，因此人类可以准确查看发生了什么，而不必只相信摘要：

个人日程规划器也是功能的一部分，因此 Agent 可以为刚刚分流的工作安排时间：

托管版快速开始（推荐）

生产环境端点：

https://mcp.kelvia.app/mcp

默认使用 OAuth。客户端会在浏览器中打开 Kelvia，由你批准访问权限，然后客户端保存并刷新 OAuth 凭据。无需将 API 令牌粘贴到配置文件中。

Claude Code

claude mcp add --transport http --scope user kelvia https://mcp.kelvia.app/mcp
claude mcp list

启动 Claude Code，输入 /mcp，选择 kelvia，然后在浏览器中完成身份验证。身份验证完成后，使用以下命令验证连接：

List my Kelvia boards.

Codex 应用、CLI 和 IDE 扩展

codex mcp add kelvia --url https://mcp.kelvia.app/mcp
codex mcp login kelvia
codex mcp list

Codex 应用、CLI 和 IDE 扩展在 Codex 主机上共用相同的 MCP 配置。在交互式 Codex 会话中，使用 /mcp 检查服务。

等效的 ~/.codex/config.toml：

[mcp_servers.kelvia]
url = "https://mcp.kelvia.app/mcp"
auth = "oauth"

Cursor

在 ~/.cursor/mcp.json 中全局添加服务，或在 .cursor/mcp.json 中按项目添加：

{
  "mcpServers": {
    "kelvia": {
      "url": "https://mcp.kelvia.app/mcp"
    }
  }
}

打开Cursor 设置 → 工具与 MCP，启用 kelvia，然后选择连接，在浏览器中完成 OAuth。Cursor 显示服务已连接后，让它列出你的 Kelvia 看板。

Agent 密钥身份验证

OAuth 会以批准访问的 Kelvia 用户身份执行操作。如果连接需要独立的身份、看板成员资格、角色、有效期以及细粒度的读取／创建／编辑／删除权限范围，请改用 Agent 密钥。

在Kelvia → 个人资料 → Agents中创建：

1. 创建 Agent 身份。
2. 仅将其添加到所需的看板，并选择其看板角色。
3. 创建具有最低必要权限范围和到期日期的密钥。
4. 出现 klv_… 值时将其复制；Kelvia 只会存储其哈希值。

使用 Agent 密钥的 Codex

将令牌保留在环境变量中；Codex 只会存储变量名称：

export KELVIA_API_TOKEN='klv_your_agent_key'
codex mcp add kelvia --url https://mcp.kelvia.app/mcp \
  --bearer-token-env-var KELVIA_API_TOKEN
codex mcp list

等效的 ~/.codex/config.toml：

[mcp_servers.kelvia]
url = "https://mcp.kelvia.app/mcp"
bearer_token_env_var = "KELVIA_API_TOKEN"

使用 Agent 密钥的 Claude Code

Claude Code 会在 MCP JSON 中展开环境变量。以下配置中的单引号可避免 shell 将令牌展开到命令历史中：

export KELVIA_API_TOKEN='klv_your_agent_key'
claude mcp add-json --scope user kelvia \
  '{"type":"http","url":"https://mcp.kelvia.app/mcp","headers":{"Authorization":"Bearer ${KELVIA_API_TOKEN}"}}'
claude mcp list

不要将令牌放入 URL。Streamable HTTP 端点只接受通过 Authorization 标头进行的身份验证。

本地 stdio 配置

大多数人应使用上方的托管端点。 在本地运行服务并不会让任务留在你的机器上——无论如何，任务都保存在 Kelvia 中，本地进程也会调用同一个 API。不同之处在于凭据的传递路径，以及哪些客户端可以连接。

在以下任一情况下使用 stdio：

• 你的客户端不支持远程 MCP 或 OAuth。 主流客户端都支持，但较旧版本、某些 IDE 插件，以及浏览器重定向无法打开的受限机器不支持。
• **你在 CI 中进行自动化，**而且没有人可以批准 OAuth 提示词。（使用 Agent 密钥连接托管端点也可行——这只是移除了一项依赖。）
• 你的密钥不应离开机器。 使用托管端点时，你的令牌会发送到 mcp.kelvia.app，并在会话期间保留在其内存中；使用 stdio 时，令牌只会发送到 Kelvia API。

要求：Node.js 20+。

无需安装即可运行已发布的软件包：

npx kelvia-mcp

或者从源代码构建（Node.js 20+ 和 pnpm 9+），然后在客户端配置中使用 dist/index.js 的绝对路径：

git clone https://github.com/gonnagetapower/kelvia-mcp.git
cd kelvia-mcp
pnpm install
pnpm build

Claude Desktop 的 MCP Bundle

如需在 Claude Desktop 中本地安装，请构建 MCP Bundle（.mcpb）：

pnpm run bundle:mcpb

这会生成 build/kelvia-mcp-<version>.mcpb。在 Claude Desktop 中打开该文件，并在提示时输入专用的 Kelvia Agent 密钥。此 Bundle 是相同本地 stdio 服务的打包形式；如需使用托管 OAuth 连接，请改用推荐的快速入门。

Claude Code（stdio）

claude mcp add --scope user \
  --env KELVIA_API_TOKEN=klv_your_agent_key \
  --transport stdio kelvia -- node /absolute/path/to/kelvia-mcp/dist/index.js

Codex（stdio）

codex mcp add kelvia \
  --env KELVIA_API_TOKEN=klv_your_agent_key \
  -- node /absolute/path/to/kelvia-mcp/dist/index.js

Cursor（stdio）

{
  "mcpServers": {
    "kelvia": {
      "command": "node",
      "args": ["/absolute/path/to/kelvia-mcp/dist/index.js"],
      "env": {
        "KELVIA_API_TOKEN": "klv_your_agent_key"
      }
    }
  }
}

可用工具

58 个工具

看板（9） — list_boards、get_board、create_board、update_board、 archive_board、unarchive_board、delete_board、list_board_columns、 get_board_activity

任务（12） — list_tasks、list_daily_tasks、list_calendar_tasks、 get_task、get_task_by_number、create_task、update_task、reorder_task、 delete_task、get_task_activity、get_task_summary、set_task_summary

评论和工作日志（8） — get_task_comments、add_task_comment、 update_task_comment、delete_task_comment、get_task_worklogs、 add_task_worklog、update_task_worklog、delete_task_worklog

阶段（8） — create_board_stage、materialize_board_backlog_stage、 update_board_stage、delete_board_stage、reorder_board_stages、 start_board_stage、complete_board_stage、reopen_board_stage

成员和邀请（9） — list_board_members、update_board_member、 remove_board_member、list_board_invitations、create_board_invitation、 revoke_board_invitation、list_my_invitations、accept_board_invitation、 decline_board_invitation

个人日程规划器（8） — list_daily_plan_blocks、 list_daily_plan_definitions、list_overdue_daily_plan_blocks、 create_daily_plan_block、update_daily_plan_block、 set_daily_plan_block_status、reorder_daily_plan_blocks、 delete_daily_plan_block

标签（3） — list_board_tags、list_tags、create_board_tag

核心（1） — get_current_user

该服务还发布了两个提示词（create_task_from_pr 和 triage_board_backlog），以及位于 kelvia://schema/… 下的两个架构资源。

每个工具都带有 MCP 注释——readOnlyHint、destructiveHint、 idempotentHint——客户端据此可以自动批准读取操作，并在删除前提示用户。58 个工具中有 22 个为只读。

工具集

完整接口在每个会话中约占 45 KB 的 JSON 架构。仅加载工作流所需的部分：

工具集	工具数	覆盖范围
boards	9	看板、列、看板活动
tasks	12	任务、任务活动、AI 摘要
comments	8	评论和工作日志
stages	8	冲刺和里程碑
members	9	成员、角色、邀请
planner	8	个人时间块日程计划
tags	3	看板和工作区标签

始终会发布 get_current_user。省略此设置，或指定不存在的工具集，都会发布所有工具。

# stdio: environment variable
KELVIA_TOOLSETS=tasks,planner npx kelvia-mcp

# hosted: header (preferred)
X-MCP-Toolsets: tasks,planner

# hosted: query parameter, for clients that cannot set headers
https://mcp.kelvia.app/mcp?toolsets=tasks,planner

tasks,planner 会发布 21 个工具，架构约占 20 KB，而非 45 KB。

良好的入门提示词

List my Kelvia boards.

On board "product", show open high-priority tasks and suggest a triage order.
Do not modify anything.

Create a task on board "product" titled "Fix the login redirect", assign high
priority, and show me the created task.

Plan today using my three most urgent assigned tasks. Show the proposed blocks
before creating them.

安全模型

• 远程令牌仅接受放在 Authorization: Bearer … 标头中的令牌。
• OAuth 使用带 PKCE 的授权码流程和动态客户端注册。
• OAuth 令牌无法管理账户凭据、个人 API 令牌、Agent 或 MCP 连接。
• Agent 密钥在静态存储时会经过哈希处理，可撤销、可设置过期时间，并受密钥范围和看板角色双重限制。
• 远程会话会显示在 Kelvia 个人资料中，并可撤销。
• 为旧版客户端提供了 /sse 传统 SSE；由于浏览器 EventSource 无法设置标头，可能需要查询令牌。建议使用 /mcp，以免凭据进入 URL、浏览器历史记录或代理访问日志。

请将 MCP 服务视为具有特权的集成。在批准请求的写入操作前先进行审核，自动化时使用专用 Agent 密钥，并且只授予工作流所需的看板和范围。

报告漏洞：请参阅 SECURITY.md。托管端点的数据处理方式见 AI 和 MCP 数据处理政策，隐私政策则涵盖整个 Kelvia。

隐私政策

MCP Bundle 会连接到 Kelvia API，并发送执行你所要求操作所需的请求。它不会运行独立的分析或广告服务。安装前，请阅读 Kelvia 隐私政策和 AI 和 MCP 数据处理政策。

自托管 HTTP 端点

设置 PORT 会将进程从 stdio 切换为 Streamable HTTP。

docker build -t kelvia-mcp .
docker run --rm -p 8080:8080 \
  -e KELVIA_API_URL=https://api.kelvia.app/api \
  -e MCP_PUBLIC_URL=https://mcp.example.com \
  kelvia-mcp

然后检查 GET /health，它会报告可用的传输方式和工具集。

环境变量

变量	模式	用途
KELVIA_API_TOKEN	stdio	Agent 密钥或个人令牌
KELVIA_API_URL	both	API 基础地址；默认为 https://api.kelvia.app/api
KELVIA_TOOLSETS	both	逗号分隔的工具集；默认全部
PORT	hosted	启用 HTTP 模式并选择监听端口
MCP_PUBLIC_URL	hosted	受保护资源的公开源地址
MCP_AUTHORIZATION_SERVER	hosted	OAuth 授权服务器源地址
MCP_ALLOWED_ORIGINS	hosted	逗号分隔的 CORS 允许列表
MCP_RATE_LIMIT	hosted	每个令牌每分钟的请求数；默认为 300
MCP_INSTANCE_COUNT	hosted	HTTP 实例数
MCP_STICKY_SESSIONS	hosted	多实例传统 SSE 的必需设置

Streamable HTTP 在 MCP 传输层是无状态的。传统 SSE 会话存储在进程内存中，因此 SSE 需要单个实例或粘性会话。

故障排查

• 需要身份验证 / HTTP 401 — 在客户端的 MCP 面板中完成 OAuth，或确认客户端进程可以访问 Bearer 令牌环境变量。
• HTTP 403 — 密钥缺少所需的作用域、Agent 缺少所需的看板角色，或电子邮件 / 账户状态阻止了该操作。
• 服务已连接，但看板缺失 — 将 Agent 身份添加到该看板，或使用已拥有访问权限的用户批准 OAuth。
• stdio 模式下出现 Connection closed — 运行 pnpm build，使用绝对路径，并确认已安装 Node.js 20+，且存在 KELVIA_API_TOKEN。
• 看不到工具 — 检查 claude mcp list、codex mcp list 或 Cursor 的 Tools & MCP 面板；更改配置后，重启 / 重新加载客户端。
• 任务输出过大 — 使用精简版 list_tasks，按看板 / 状态筛选，然后对单条记录调用 get_task，而不要请求详细列表。
• 客户端可用的工具过多 — 使用 工具集 缩小范围。

健康状态和 OAuth 发现：

GET https://mcp.kelvia.app/health
GET https://mcp.kelvia.app/.well-known/oauth-protected-resource/mcp
GET https://api.kelvia.app/.well-known/oauth-authorization-server

开发

pnpm install
pnpm run lint
pnpm run typecheck:strict
pnpm run test

pnpm run test 会构建此软件包，通过官方 MCP 客户端 SDK 初始化 stdio 服务，并验证已发布的工具、注释、工具集、提示词、资源和服务说明。

请参阅 CONTRIBUTING.md，了解此代码库与 Kelvia 单体仓库的关系，以及修改工具需要涉及哪些内容。

许可证

MIT