Vikunja MCP for Codex

在 Codex 中使用自然语句来读取和管理你自己的 Vikunja 账户中的任务。

例如，你可以这样问 Codex：

Show my open Vikunja tasks.
Create a task called "Prepare the launch checklist" in my Website Redesign project.
Mark task 42 as complete.

你无需输入 / 命令或使用 @ 提及插件。安装后，在新的 Codex 任务中自然地提问即可。

为什么需要这个插件

Vikunja 和 Codex 本身无法直接通信：

• Vikunja 为项目和任务提供 HTTP API。

• Codex 在需要与其他应用协作时使用 MCP 工具。

• 这个插件就是一座小型桥梁，将 Codex 的 MCP 请求转换为 Vikunja 的 API 请求。

You → Codex → this plugin → your Vikunja API → your tasks

该插件不会替代 Vikunja、托管第二个任务数据库或直接访问 Vikunja 数据库。Vikunja 仍然控制着登录、权限、验证和存储。

Related MCP server: Vikunja MCP Server

它能做什么

• 列出和创建 Vikunja 项目。

• 列出项目中的任务。

• 创建和更新任务。

• 标记任务为完成。

删除操作特意未包含在此初始版本中。

新手安装

以下说明适用于首次用 Codex 设置新电脑的用户。

1. 安装 Codex CLI

本指南中的终端命令需要 Codex CLI，即使你也使用 Codex 桌面应用。

在 macOS 或 Linux 上，使用官方安装程序：

curl -fsSL https://chatgpt.com/codex/install.sh | sh

对于 Windows 和其他安装方式，请参考 官方 Codex CLI 指南。

打开一个新的终端，确认安装成功，然后登录：

codex --version
codex

如果终端显示 codex: command not found，请先关闭并重新打开终端。如果仍然失败，请返回官方安装指南，检查 Codex 安装目录是否已添加到你的 PATH 环境变量中。

2. 安装 Node.js 和 Git

安装：

• Node.js 版本 20 或更新。选择最新的 LTS 版本，除非你有特殊原因不这么做。

• Git，在直接从 GitHub 安装时会用到。

安装 Node.js 也会安装 npm 和 npx。在新终端中检查所有内容：

node --version
npm --version
npx --version
git --version

正常使用无需运行 npm install。完成的 MCP 服务器及其依赖项已捆绑在此仓库中。

3. 从 GitHub 安装插件

此仓库必须是公开的 DanJamesMills/vikunja-mcp，上述命令才能对其他用户生效。

将 GitHub 仓库添加为 Codex 插件市场：

codex plugin marketplace add DanJamesMills/vikunja-mcp --ref main

从中安装 Vikunja 插件：

codex plugin add codex-vikunja@vikunja-mcp

确认 Codex 能识别它：

codex plugin list

添加市场后，也可以在 Codex 桌面应用的插件目录中查看和管理该插件。

4. 创建 Vikunja API 令牌

登录你自己的 Vikunja 网站，然后打开：

设置 → API 令牌

创建一个专用的令牌，授予你希望 Codex 拥有的读取和写入权限。在 Vikunja 显示令牌时复制它。

5. 将插件连接到 Vikunja

运行引导式设置：

npx --yes github:DanJamesMills/vikunja-mcp setup

它会要求输入：

1. 你的 Vikunja URL，例如 https://tasks.example.com。

2. 你的 Vikunja API 令牌。令牌输入是隐藏的。

设置会在保存前检查连接。每个用户都需要输入自己的 URL 和令牌；此公开仓库中不包含任何凭据。

npx 仅下载并运行来自此 GitHub 仓库的设置命令。它已随 Node.js 一起安装，因此无需单独安装 npx。

6. 重启 Codex 并测试

关闭并重新打开 Codex，或者启动一个新的 Codex 任务，以便加载新安装的 MCP 服务器。然后提问：

List my Vikunja projects.

之后再尝试写入操作：

Create a task called "Test the Vikunja Codex plugin" in project 12.

这就是完整的普通用户设置流程。

重启后还能用吗？

可以。设置会将 URL 和令牌保存在你操作系统的用户应用数据文件夹中。当 Codex 再次启动插件时，它会自动读取同一个文件。

这些设置也能在插件更新后保留。你无需在重启终端、Codex 或电脑后再次导出令牌。

检查、更改或移除已保存的连接

随时使用以下命令：

npx --yes github:DanJamesMills/vikunja-mcp status
npx --yes github:DanJamesMills/vikunja-mcp configure
npx --yes github:DanJamesMills/vikunja-mcp logout

• status 会显示设置是否存在，但绝不会显示令牌。

• configure 会验证并保存不同的 URL 或令牌。

• logout 会请求确认并移除已保存的设置文件。

更改或移除连接后，请重启 Codex 或打开一个新任务。移除已保存的连接与卸载插件本身是分开的。要同时移除已保存的连接和已安装的插件，请运行：

npx --yes github:DanJamesMills/vikunja-mcp logout
codex plugin remove codex-vikunja@vikunja-mcp

也可以从 Codex 插件目录中卸载该插件。

设置存储位置

• macOS：~/Library/Application Support/vikunja-mcp/config.json

• Windows：%APPDATA%\vikunja-mcp\config.json

• Linux：$XDG_CONFIG_HOME/vikunja-mcp/config.json 或 ~/.config/vikunja-mcp/config.json

JSON 文件以纯文本形式包含 Vikunja URL 和 API 令牌。在 macOS 和 Linux 上，设置过程会应用仅拥有者可访问的目录和文件权限（0700 和 0600）。在 Windows 上，文件会继承当前用户的应用数据权限。

请保护好你的操作系统账户，创建一个仅包含所需权限的专用 Vikunja 令牌，并且永远不要将真实的令牌提交或粘贴到公开的问题中。请参阅 SECURITY.md。

早期测试版本使用了 macOS 钥匙串。运行 setup 或 logout 也会清理旧的测试条目。

多个 Vikunja 安装

此公开插件适用于自托管 Vikunja 和 Vikunja Cloud，因为每个用户都需提供自己的 URL 和令牌。

此版本支持每台电脑连接一个活跃的 Vikunja 安装。运行 configure 可切换到其他安装。

可选的环境变量

高级用户和服务器可以在没有设置文件的情况下提供配置：

• VIKUNJA_URL

• VIKUNJA_API_TOKEN

环境变量会覆盖已保存的设置。URL 可以是 https://tasks.example.com 或 https://tasks.example.com/api/v1；插件会自动标准化这两种形式。

macOS 和 Linux

export VIKUNJA_URL="https://tasks.example.com"
export VIKUNJA_API_TOKEN="tk_your_token"
codex

Windows PowerShell

$env:VIKUNJA_URL = "https://tasks.example.com"
$env:VIKUNJA_API_TOKEN = "tk_your_token"
codex

在一个终端中导出的变量通常会在该终端关闭后消失。对于桌面使用，引导式设置更简单，因为其设置在重启后仍然保留。

更新插件

从 GitHub 拉取最新的市场信息：

codex plugin marketplace upgrade vikunja-mcp

然后从插件目录安装可用的 Vikunja 更新，或再次运行插件安装命令：

codex plugin add codex-vikunja@vikunja-mcp

更新后启动一个新的 Codex 任务。对于生产版本，从标记的 Git 版本安装比跟随 main 分支更安全，因为版本是固定的。

包含的 MCP 工具

• vikunja_list_projects

• vikunja_create_project

• vikunja_list_tasks

• vikunja_create_task

• vikunja_update_task

• vikunja_complete_task

大多数用户无需了解这些名称；它们是根据你的自然语言请求，Codex 从中选择内部工具。

贡献者指南

只有修改插件源码的贡献者才需要克隆仓库并安装其开发依赖：

git clone https://github.com/DanJamesMills/vikunja-mcp.git
cd vikunja-mcp
npm install
npm test
npm run build

当源码或依赖项发生变化时，请提交重新构建的 mcp/server.bundle.mjs。已安装的用户运行该捆绑包，因此他们不需要本地的 node_modules 目录。

从克隆的仓库中测试入门捆绑包：

node mcp/server.bundle.mjs setup
node mcp/server.bundle.mjs status
node mcp/server.bundle.mjs logout

使用临时值运行配置检查：

VIKUNJA_URL="https://tasks.example.com" \
VIKUNJA_API_TOKEN="tk_test_token" \
npm run check

令牌提示是隐藏的。永远不要将真实的令牌放入命令参数、测试夹具、shell 历史记录或 Git 提交中。

请从 docs/FOLDER-GUIDE.md 开始，了解每个文件的作用以及请求如何通过插件传递。

npm 发布

该软件包标记为 private，以防止意外发布到 npm。GitHub 安装使用已提交的捆绑包，不需要 npm 包。

如果此项目日后发布到 npm，请选择并保护好软件包名称，移除 private 标识，添加发布自动化，审核依赖项，并发布不可变版本。