Vikunja tasks

emperor-vikunja

适用于 Vikunja（开源任务管理器）的 MCP 服务。 让 Claude、 kowalski 或任何 MCP 客户端列出、读取、创建和更新任务，为任务添加评论并查看项目。

基于 emperor-mcp 构建（Emperor Profile P1.1）：

• 无状态 Streamable HTTP，位于 /mcp，并为桌面客户端提供 stdio。
• 令牌仅转发，绝不存储。 使用 HTTP 时，每个请求都会携带自己的 Authorization: Bearer <token>；服务会将其传递给 Vikunja，然后立即丢弃。没有默认令牌或测试令牌。
• 带框架标记的输出。 用户编写的任务文本（标题、描述、评论）会被标记为面向用户的消息，而非模型指令。
• 默认只读，除非你另有选择。 服务以默认配置启动时只提供三个读取工具；--writable（或 VIKUNJA_WRITABLE=true）会添加另外三个可修改任务的工具。
• 六个带注释的工具，定义简洁，包含 doctor 子命令，支持 Markdown 输入并输出纯文本。
• 清晰的身份验证失败提示。 Vikunja 拒绝令牌时，HTTP 上的 MCP 响应会返回 401 或 403，以便客户端请求新令牌。

工具

工具	列出方式	注解	功能
list_tasks	始终	只读	按优先级、再按截止日期排序的任务。筛选条件：project（标题或 ID）、label、done（默认为 false）、due_before、search；limit 最大为 100（默认为 50）。返回 ID、标题、项目、标签、受派人、优先级、截止日期和完成状态。
get_task	始终	只读	按 id 获取单个任务：所有字段、纯文本格式的描述（前 20 000 个字符），以及最近的 50 条评论（包含作者和日期，每条最多 4 000 个字符）。
create_task	使用 --writable 时	写入，非幂等	project、title、可选的 description（Markdown）、labels、create_missing_labels、assignees（用户名）、priority（0-5）、due。
update_task	使用 --writable 时	写入，有破坏性，幂等	id，以及以下任意字段：title、description、done、priority、due（"none" 可清除截止日期）、add_labels、remove_labels、create_missing_labels、add_assignees、remove_assignees、project（移动任务）。
comment	使用 --writable 时	写入，非幂等	为任务 id 添加一条 Markdown 评论。
list_projects	始终	只读	项目（最多 100 个），包含 ID、标题、父项目和未完成任务数量。

不使用 --writable 时，写入工具完全不会出现在服务中：既不会列出，也无法调用，因此模型和它读取的文本都无法访问这些工具。

每个工具都标记为开放世界（它会与其他人也在修改的 Vikunja 通信）。 update_task 标记为有破坏性，因为新标题或描述会替换旧文本，而 Vikunja 不会保留旧文本；标签和受派人也可以被移除。它是幂等的，因为相同的调用执行两次后，任务状态与只执行一次相同。

标签以标题命名。除非调用传入 create_missing_labels: true，否则不存在的标签会导致错误，因此拼写错误不会悄悄添加新标签。受派人使用用户名（必须完全匹配，但不区分大小写；可以带前导 @）。写入任何内容前都会检查名称：标签或用户名无效时，不会留下创建到一半的任务。

优先级：0 未设置，1 低，2 中，3 高，4 紧急，5 立即处理。日期：YYYY-MM-DD（按 00:00 UTC 读取）或 ISO-8601；返回的日期采用 RFC 3339 格式，未设置时为 null。

Vikunja 会将描述和评论存储为 HTML。模型以 Markdown 写入的内容会在写入时转换为 HTML（Markdown 中的原始 HTML 会被转义，不会直接传入）；读回的 HTML 会转换为纯文本。

安装

从发行版安装（Linux x86_64、macOS arm64 和 x86_64、Windows x86_64）：从 Releases 下载适用于你平台的压缩包，并将 emperor-vikunja 放到 PATH 中。

从源代码安装（Rust 1.88 或更高版本）：

cargo install --git https://github.com/yarenty/emperor-vikunja

获取令牌

在 Vikunja 中打开 设置 > API Tokens > 创建令牌，选择到期日期，并勾选以下权限（使用 --writable 时六个工具所需的最小权限）：

分组	权限
projects	read_all、read_one
tasks	read_all、read_one、create、update
tasks_comments	read_all、create
tasks_labels	read_all、create、delete
tasks_assignees	read_all、create、delete
labels	read_all、create（仅当使用 create_missing_labels 时需要 create）
other	user（允许 doctor 显示令牌所属用户）、users（通过用户名指定受派人）

服务默认只读；如果要提供给只读助手使用，请使用仅包含 read_all / read_one 权限的令牌（并为 doctor 添加 other: user）。

运行

本地（stdio）

export VIKUNJA_TOKEN=...            # from Settings > API Tokens
emperor-vikunja serve --stdio --base-url https://vikunja.example.com              # read-only
emperor-vikunja serve --stdio --base-url https://vikunja.example.com --writable   # also create, update, comment

Docker（stdio）

docker build -t emperor-vikunja https://github.com/yarenty/emperor-vikunja.git
docker run -i --rm -e VIKUNJA_URL=https://vikunja.example.com -e VIKUNJA_TOKEN emperor-vikunja
# read-only by default; to create, update and comment add -e VIKUNJA_WRITABLE=true
# (or --writable after the image name)

该镜像会以非 root 用户身份运行 emperor-vikunja serve --stdio；Vikunja 地址来自 VIKUNJA_URL。

共享（HTTP）

# --writable: the users of this server may create, update and comment; leave it out for read-only
emperor-vikunja serve --base-url https://vikunja.example.com --bind 127.0.0.1:8034 --writable
# MCP endpoint: http://127.0.0.1:8034/mcp   liveness: http://127.0.0.1:8034/health

每个 MCP 请求都必须携带 Authorization: Bearer <token>；每位用户都要提供自己的令牌。 此模式下会忽略 VIKUNJA_TOKEN，因此一个人的令牌绝不会用于响应另一个人的请求。工具发现（tools/list）无需令牌。

当 Vikunja 拒绝令牌（401），或令牌可能无权执行此操作（403）时，MCP 响应会携带相应的 HTTP 状态（401 时附带 WWW-Authenticate: Bearer error="invalid_token"）以及错误代码为 -32040、包含 data.httpStatus 的 JSON-RPC 错误。使用 stdio 时，客户端会收到相同的 JSON-RPC 错误。

标志和请求头

标志	环境变量	含义
--base-url <URL>	VIKUNJA_URL	Vikunja 地址；https://host 和 https://host/api/v1 均可使用。与 --stdio 一起使用时必填；使用 HTTP 时可选，但请求必须发送 X-Upstream-Url。
--writable	VIKUNJA_WRITABLE	同时提供 create_task、update_task 和 comment。未启用时，服务为只读：写入工具不会出现在服务中，而不只是被拒绝。环境变量值为 true、1、yes 或 on 时启用；未设置、为空、值为 false、0、no 或 off 时保持关闭；其他值会导致服务在启动时停止。
--read-only	VIKUNJA_READ_ONLY	已弃用，无效：默认就是只读。仍接受此选项，以便现有配置可以启动；会记录一条单行提示。与 --writable 一起指定时，服务会拒绝启动。
--stdio		通过 stdin/stdout 使用 MCP；令牌来自 VIKUNJA_TOKEN。
--bind <ADDR>		HTTP 监听地址（默认值为 127.0.0.1:8034）。
--allowed-host <HOST>		仅接受此 Host 请求头（可重复指定）；默认关闭，适用于前置验证代理的场景。
--allowed-origin <ORIGIN>		仅接受此 Origin（可重复指定），例如 https://app.example.com。

请求头（HTTP）	含义
Authorization: Bearer <token>	调用方的 Vikunja API 令牌。每次工具调用都必须提供。
X-Upstream-Url: <URL>	此请求所使用的 Vikunja 实例，覆盖 --base-url。必须使用 https；仅当主机为环回地址（localhost、127.0.0.0/8、::1）时才接受普通 http。

使用 X-Upstream-Url 时，一个服务可以代理多个 Vikunja 实例。此时，服务会使用客户端提供的令牌，向客户端指定的任意 https 主机发起调用；请仅在允许向任意主机发起出站调用的环境中运行，或者在代理处移除此请求头并使用 --base-url。

日志输出到 stderr；设置 RUST_LOG=debug 可查看更多信息。生产环境中，请将 HTTP 服务置于负责终止 TLS 的反向代理之后（Emperor Profile E5）。

连接

Claude Desktop（claude_desktop_config.json）：

--writable 允许 Claude 创建、更新和评论；如需只读连接，请移除此选项。

{
  "mcpServers": {
    "vikunja": {
      "command": "emperor-vikunja",
      "args": ["serve", "--stdio", "--base-url", "https://vikunja.example.com", "--writable"],
      "env": { "VIKUNJA_TOKEN": "<your token>" }
    }
  }
}

Claude Code：

# stdio, read-only (the default)
claude mcp add vikunja-ro --env VIKUNJA_TOKEN=<your token> -- \
  emperor-vikunja serve --stdio --base-url https://vikunja.example.com
# stdio, --writable: Claude may also create, update and comment
claude mcp add vikunja --env VIKUNJA_TOKEN=<your token> -- \
  emperor-vikunja serve --stdio --base-url https://vikunja.example.com --writable
# or against a running HTTP server (its own --writable decides what is listed)
claude mcp add --transport http vikunja http://127.0.0.1:8034/mcp \
  --header "Authorization: Bearer <your token>" \
  --header "X-Upstream-Url: https://vikunja.example.com"

kowalski（config.toml）：

[[mcp.servers]]
name = "vikunja"
transport = "stdio"
# --writable: the agent may create, update and comment; drop it for read-only.
command = ["emperor-vikunja", "serve", "--stdio", "--base-url", "https://vikunja.example.com", "--writable"]
# VIKUNJA_TOKEN is read from kowalski's environment.

# or over HTTP (the server's own --writable decides what is listed)
[[mcp.servers]]
name = "vikunja-http"
transport = "http"
url = "http://127.0.0.1:8034/mcp"
headers = { Authorization = "Bearer <your token>", X-Upstream-Url = "https://vikunja.example.com" }

Doctor

emperor-vikunja doctor 会在启动服务前检查配置；如有问题则以状态码 1 退出，因此脚本和容器健康检查可以使用它：

$ VIKUNJA_TOKEN=... emperor-vikunja doctor --base-url https://vikunja.example.com
emperor-vikunja 0.2.0 doctor
  [ok  ] base url        https://vikunja.example.com/
  [ok  ] vikunja api     Vikunja v2.7.1
  [ok  ] VIKUNJA_TOKEN   set (43 chars)
  [ok  ] vikunja login   token works for user alice
  [ok  ] mode            read-only: get_task, list_projects, list_tasks (pass --writable or VIKUNJA_WRITABLE=true for create_task, update_task, comment)
  [ok  ] listen address  127.0.0.1:8034 is free
  [ok  ] tool budget     3 of at most 8 tools
all good (0 warning(s))

它会检查 URL 是否能解析、GET /api/v1/info 是否有响应、令牌是否已设置（仅显示长度）以及 GET /api/v1/user 是否接受该令牌、当前模式会提供哪些工具（默认提供三个读取工具，使用 --writable 时提供全部六个工具；指定已弃用的 --read-only 时会发出警告）、监听地址是否空闲（使用 --stdio 时跳过），以及工具数量是否在 emperor-mcp 的限额内。HTTP 模式下若未设置 VIKUNJA_TOKEN，令牌这一项会显示为警告，因为令牌会随请求提供；使用 --stdio 时则会判定为失败。--base-url 也一样：HTTP 模式下未指定时会显示为警告（请求必须发送 X-Upstream-Url），使用 --stdio 时则会判定为失败。

兼容性

已针对 Vikunja v2.7（vikunja/vikunja 镜像）进行测试。任务通过 GET /tasks 和 Vikunja 的筛选语法列出（done = false && project = 3 && labels in 5 && due_date < '...'）；对于仍提供 /tasks/all 的旧版本，会自动使用该接口，并在本地重新应用每项筛选条件，确保即使服务端忽略了部分条件，结果仍然正确。

构建和测试

cargo test                                               # unit, fake-Vikunja, MCP HTTP and stdio tests
cargo test --test live_vikunja -- --ignored --nocapture  # default and --writable against a real Vikunja in Docker

链接

• Crate：crates.io/crates/emperor-vikunja，API 文档见 docs.rs
• 容器：根据 Dockerfile 构建；容器通过 stdio 提供服务，并读取 VIKUNJA_URL、VIKUNJA_TOKEN 和 VIKUNJA_WRITABLE
• 已列入官方 MCP Registry，mcp-name 为：io.github.yarenty/emperor-vikunja
• 与其他任务管理器 MCP 服务的比较：docs/COMPARISON.md

许可证

可选择以下任一许可证：

• Apache License, Version 2.0（LICENSE-APACHE 或 https://www.apache.org/licenses/LICENSE-2.0）
• MIT license（LICENSE-MIT 或 https://opensource.org/licenses/MIT）

由你自行选择。

除非你明确声明另有安排，否则你有意提交以纳入 emperor-vikunja 的任何贡献，均将按照上述条款采用双重许可，不附加任何其他条款或条件。