使用说明

Vikunja MCP服务器

用于管理Vikunja项目和任务的模型上下文协议服务器。

快速开始

直接使用npx运行（无需安装）：

npx vikunja-mcp --token YOUR_VIKUNJA_TOKEN

使用自定义Vikunja URL：

npx vikunja-mcp --url https://your-vikunja.com/api/v1 --token YOUR_TOKEN

或者使用环境变量：

export VIKUNJA_TOKEN=your_token
export VIKUNJA_URL=https://your-vikunja.com/api/v1
npx vikunja-mcp

特性

项目的完整CRUD操作
任务的完整CRUD操作
任务评论管理
任务关系（子任务、阻塞等）
任务附件列表
任务分配人员管理
任务标签管理
项目层次（epics）管理

可用工具

项目

工具	说明
`list_projects`	列出用户有权访问的所有项目
`get_project`	按ID获取特定项目
`create_project`	创建新项目
`update_project`	更新现有项目
`delete_project`	按ID删除项目
`list_project_children`	列出项目下的子项目
`move_project`	将项目移动到不同的父/位置

任务

工具	说明
`list_tasks`	列出所有项目中的所有任务
`list_project_tasks`	列出特定项目的所有任务
`get_task`	按ID获取特定任务
`create_task`	在项目中创建新任务
`update_task`	更新现有任务
`delete_task`	按ID删除任务

任务状态和运动

工具	说明
`complete_task`	将任务标记为已完成
`reopen_task`	重新打开已完成的任务
`move_task`	将任务移动到不同的项目/职位

受托人

工具	说明
`add_task_assignee`	将用户添加为任务的受让人
`remove_task_assignee`	从任务中删除受让人
`list_task_assignees`	列出任务的所有指定人员

关系

工具	说明
`create_relation`	在两个任务之间创建关系
`delete_relation`	删除任务之间的关系
`list_task_relations`	列出任务的所有关系

子任务

工具	说明
`create_subtask`	创建链接到父任务的子任务
`list_subtasks`	列出任务的所有子任务

附件

工具	说明
`list_task_attachments`	列出任务的所有附件
`delete_task_attachment`	从任务中删除附件

有关所有工具的完整参数文档，请参阅下文。

工具参考

参数类型

字符串：文本值
数字：数值（整数）
布尔：真/假值
必需的：必须提供此参数
可选的：此参数可以省略

备注：所有ID参数（例如。， projectId, taskId)接受数字和字符串值。MCP服务器使用 z.coerce.number() 自动将字符串ID（如“123”）转换为数字。这意味着你可以通过 123 或 "123" 对于任何ID参数。看使用字符串ID 例如。

项目

list_项目

列出用户有权访问的所有项目。

参数：无需
可选的:
- page （number）：分页页码
- per_page （number）：每页项目数（默认值：25）

get_工程

按ID获取特定项目。

参数:
- projectId （数字，必填）：项目ID

创建项目

创建一个新项目。

参数:
- title （string，必填）：项目标题
可选的:
- description （string）：项目描述
- hex_color （字符串）：十六进制颜色代码（例如“#FF5733”）
- identifier （string）：项目的唯一标识符
- parent_project_id （编号）：父项目的ID（用于史诗/层次结构）
- is_archived （boolean）：项目是否存档

update_项目

更新现有项目。

参数:
- projectId （数字，必填）：项目ID
可选的:
- title （string）：新标题
- description （string）：新描述
- hex_color （string）：新的十六进制颜色代码
- identifier （string）：新标识符
- parent_project_id （编号）：新的父项目ID
- is_archived （布尔值）：存档状态

删除项目

按ID删除项目。

参数:
- projectId （数字，必填）：项目ID

列表_项目_儿童

列出项目下的子项目。

参数:
- projectId （数字，必填）：父项目ID

move_项目

将项目移动到不同的父级或位置。

参数:
- projectId （数字，必填）：项目ID
可选的:
- parent_project_id （number）：新的父项目ID（空可从父项目中删除）
- position （编号）：母项目中的新职位

任务

list_tasks

列出所有项目中的所有任务。

参数：无需
可选的:
- page （number）：分页页码
- per_page （number）：每页项目数
- status （string）：按状态筛选（打开、完成、done_lte、done_gate）
- priority （数字）：按优先级筛选
- due_date （string）：按截止日期筛选
- label （string）：按标签筛选

list_project_tasks

列出特定项目的所有任务。

参数:
- projectId （数字，必填）：项目ID
可选的:
- page （number）：分页页码
- per_page （number）：每页项目数

获取任务

按ID获取特定任务。

参数:
- taskId （数字，必填）：任务ID

创建任务

在项目中创建新任务。

参数:
- projectId （数字，必填）：项目ID
必需:
- task （object）：任务对象
  - title （string，必填）：任务标题
可选的:
- task （object）：任务对象
  - description （string）：任务描述
  - done （boolean）：任务是否完成
  - due_date （字符串）：到期日（ISO 8601格式）
  - start_date （string）：开始日期
  - end_date （字符串）：结束日期
  - hex_color （string）：任务颜色
  - priority （数字）：优先级（1-5，其中5为最高）
  - percent_done （数字）：进度（0-100）
  - repeat_after （数字）：X分钟后重复
  - repeat_mode （数字）：重复模式（0=相对，1=绝对）

update_task

更新现有任务。

参数:
- taskId （数字，必填）：任务ID
- taskUpdates （object，必填）：要更新的任务字段
可选的:
- taskUpdates （对象）：
  - title （string）：新标题
  - description （string）：新描述
  - done （boolean）：完成状态
  - due_date （string）：新的截止日期
  - start_date （string）：新的开始日期
  - end_date （string）：新的结束日期
  - hex_color （string）：新颜色
  - priority （数字）：新优先级
  - percent_done （数字）：进度（0-100）
  - repeat_after （数字）：新的重复间隔
  - repeat_mode （数字）：重复模式（0=相对，1=绝对）

删除任务

按ID删除任务。

参数:
- taskId （数字，必填）：任务ID

任务状态和运动

完成任务

将任务标记为已完成。

参数:
- taskId （数字，必填）：任务ID

重新打开任务

重新打开已完成的任务。

参数:
- taskId （数字，必填）：任务ID

移动任务

将任务移动到不同的项目或位置。

参数:
- taskId （数字，必填）：任务ID
- project_id （数字，必填）：目标项目ID
可选的:
- position （编号）：新职位

受托人

add_task_assignee

将用户添加为任务的受让人。

参数:
- taskId （数字，必填）：任务ID
- userId （数字，必填）：要添加的用户ID

remove_task_assignee

从任务中删除受让人。

参数:
- taskId （数字，必填）：任务ID
- userId （数字，必填）：要删除的用户ID

list_task_任务分配者

列出任务的所有指定人员。

参数:
- taskId （数字，必填）：任务ID

关系

创建关系

在两个任务之间创建关系。

参数:
- taskId （数字，必填）：源任务ID
- otherTaskId （数字，必填）：相关任务ID
- relationKind （字符串，必填）：关系类型（未知、子任务、父任务、相关、重复、重复、阻塞、阻塞、前导、跟随、复制自、复制到）

删除相关信息

删除任务之间的关系。

参数:
- taskId （数字，必填）：源任务ID
- otherTaskId （数字，必填）：相关任务ID
- relationKind （字符串，必填）：关系类型（未知、子任务、父任务、相关、重复、重复、阻塞、阻塞、前导、跟随、复制自、复制到）

list_task_relations

列出任务的所有关系。

参数:
- taskId （数字，必填）：任务ID

子任务

create_subtask

创建链接到父任务的子任务。

参数:
- projectId （数字，必填）：项目ID
- parent_task_id （数字，必填）：父任务ID
- task （object，必填）：子任务对象
必需:
- task （对象）：
  - title （字符串，必填）：子任务标题
可选的:
- task （对象）：
  - description （string）：子任务描述
  - done （boolean）：子任务是否完成
  - due_date （string）：到期日
  - start_date （string）：开始日期
  - end_date （字符串）：结束日期
  - hex_color （string）：子任务颜色
  - priority （数字）：优先级
  - percent_done （数字）：进度（0-100）
  - repeat_after （数字）：X分钟后重复
  - repeat_mode （数字）：重复模式（0=相对，1=绝对）

list_子任务

列出任务的所有子任务。

参数:
- taskId （数字，必填）：父任务ID

附件

列表任务附件

列出任务的所有附件。

参数:
- taskId （数字，必填）：任务ID
可选的:
- page （编号）：页码
- per_page （数量）：每页项目数

删除任务附件

从任务中删除附件。

参数:
- taskId （数字，必填）：任务ID
- attachmentId （数字，必填）：附件ID

例子

列出项目和任务

list my vikunja projects

返回您有权访问的所有项目。

list_project_tasks projectId: 1

返回项目ID 1中的所有任务。

list_tasks per_page: 50

列出所有项目中最多50个任务。

创建项目和任务

create_project title: "My Project" description: "A new project" hex_color: "#FF5733"

使用标题、描述和颜色创建新项目。

create_task projectId: 1 title: "Buy groceries" priority: 3 due_date: "2024-12-25"

在项目ID 1中创建具有优先级和截止日期的任务。

管理任务状态

complete_task taskId: 5

将任务5标记为已完成。

reopen_task taskId: 5

重新打开任务5。

与受让人合作

add_task_assignee taskId: 3 userId: 7

将用户7添加为任务3的受让人。

list_task_assignees taskId: 3

列出任务3的所有指定人员。

create_comment taskId: 3 comment: "This should be done by Friday"

向任务3添加注释。

关系

create_relation taskId: 1 otherTaskId: 2 relationKind: "blocking"

创建从任务1到任务2的“阻塞”关系（任务1阻塞任务2）。

使用字符串ID

所有ID参数都接受字符串，因此这些参数是等效的：

get_project projectId: 1
get_project projectId: "1"

在处理来自外部源的数据时，这很有用：

list_project_tasks projectId: "123"

安装

先决条件

Node.js 18+
npm或bun
Vikunja实例（自托管或云）
Vikunja API代币

获取Vikunja API代币

登录您的Vikunja实例
前往设置→ API令牌
创建新令牌

从源代码构建

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

OpenCode配置

选项1：使用npx（推荐）

配置Vikunja MCP最简单的方法是使用npx。将此添加到您的OpenCode配置中(~/.config/opencode/opencode.jsonc):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "vikunja": {
      "type": "local",
      "command": ["npx", "-y", "vikunja-mcp"],
      "environment": {
        "VIKUNJA_URL": "https://your-vikunja-instance.com/api/v1",
        "VIKUNJA_TOKEN": "your-api-token-here",
      },
    },
  },
}

使用npx -y 跳过确认提示并自动下载包。

选项2：从源代码构建

如果您更喜欢在本地运行而不使用npx，请从源代码构建：

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

然后配置OpenCode：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "vikunja": {
      "type": "local",
      "command": ["node", "/path/to/vikunja-mcp/dist/index.js"],
      "environment": {
        "VIKUNJA_URL": "https://your-vikunja-instance.com/api/v1",
        "VIKUNJA_TOKEN": "your-api-token-here",
      },
    },
  },
}

配置选项

选项	必填	默认	说明
`VIKUNJA_URL`	否	https://try.vikunja.io/api/v1	您的Vikunja API基础URL
`VIKUNJA_TOKEN`	是	-	您的Vikunja API令牌

环境变量

您还可以在shell中全局设置环境变量：

export VIKUNJA_URL="https://your-vikunja-instance.com/api/v1"
export VIKUNJA_TOKEN="your-api-token-here"

然后OpenCode配置可以更简单：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "vikunja": {
      "type": "local",
      "command": ["node", "/path/to/vikunja-mcp/dist/index.js"],
    },
  },
}

Claude Code桌面应用程序配置

选项1：使用npx（推荐）

配置Vikunja MCP最简单的方法是使用npx。将此添加到您的Claude Code桌面配置文件中：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %APPDATA%\Claude\claude_desktop_config.json Linux： ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "vikunja": {
      "command": "npx",
      "args": ["-y", "vikunja-mcp"],
      "env": {
        "VIKUNJA_URL": "https://your-vikunja-instance.com/api/v1",
        "VIKUNJA_TOKEN": "your-api-token-here",
      },
    },
  },
}

使用npx -y 跳过确认提示并自动下载包。

选项2：从源代码构建

如果您更喜欢在本地运行而不使用npx，请从源代码构建：

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

然后配置克劳德代码：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %APPDATA%\Claude\claude_desktop_config.json Linux： ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "vikunja": {
      "command": "node",
      "args": ["/path/to/vikunja-mcp/dist/index.js"],
      "env": {
        "VIKUNJA_URL": "https://your-vikunja-instance.com/api/v1",
        "VIKUNJA_TOKEN": "your-api-token-here",
      },
    },
  },
}

配置选项

选项	必填	默认	说明
`VIKUNJA_URL`	否	https://try.vikunja.io/api/v1	您的Vikunja API基础URL
`VIKUNJA_TOKEN`	是	-	您的Vikunja API令牌

环境变量

您还可以在shell中全局设置环境变量：

export VIKUNJA_URL="https://your-vikunja-instance.com/api/v1"
export VIKUNJA_TOKEN="your-api-token-here"

那么Claude Code配置可以更简单：

{
  "mcpServers": {
    "vikunja": {
      "command": "node",
      "args": ["/path/to/vikunja-mcp/dist/index.js"],
    },
  },
}

克劳德代码TUI配置

Claude Code TUI（终端用户界面）使用 claude mcp add 配置MCP服务器的命令。

选项1：使用npx（推荐）

配置Vikunja MCP最简单的方法是使用npx：

claude mcp add --transport stdio --env VIKUNJA_URL=https://your-vikunja-instance.com/api/v1 --env VIKUNJA_TOKEN=your-api-token-here vikunja -- npx -y vikunja-mcp

选项2：从源代码构建

如果您更喜欢在本地运行而不使用npx，请从源代码构建：

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

然后配置克劳德代码：

claude mcp add --transport stdio --env VIKUNJA_URL=https://your-vikunja-instance.com/api/v1 --env VIKUNJA_TOKEN=your-api-token-here vikunja -- /path/to/vikunja-mcp/dist/index.js

配置范围

Claude Code TUI支持MCP服务器配置的不同作用域：

范围	配置位置	描述
`user`	`~/.claude.json`	适用于所有项目
`local` （默认）	`~/.claude.json` 在项目路径下	仅在当前项目中可用
`project`	`.mcp.json` 在项目根目录中	与团队成员共享（签入源代码管理）

# Add with user scope (available across all projects)
claude mcp add --transport stdio --scope user --env VIKUNJA_TOKEN=... vikunja -- npx -y vikunja-mcp

# Add with project scope (shared with team via .mcp.json)
claude mcp add --transport stdio --scope project --env VIKUNJA_TOKEN=... vikunja -- npx -y vikunja-mcp

管理MCP服务器

# List all configured servers
claude mcp list

# Get details for a specific server
claude mcp get vikunja

# Remove a server
claude mcp remove vikunja

# Within Claude Code, check server status
/mcp

配置选项

选项	必填	默认	说明
`VIKUNJA_URL`	否	https://try.vikunja.io/api/v1	您的Vikunja API基础URL
`VIKUNJA_TOKEN`	是	-	您的Vikunja API令牌

环境变量

您还可以在shell中全局设置环境变量：

export VIKUNJA_URL="https://your-vikunja-instance.com/api/v1"
export VIKUNJA_TOKEN="your-api-token-here"

然后配置更简单：

claude mcp add --transport stdio vikunja -- npx -y vikunja-mcp

用法

CLI选项

选项	别名	描述
`--token`	`-t`	您的Vikunja API代币
`--url`	`-u`	您的Vikunja API基础URL
`--help`	`-h`	显示帮助

使用OpenCode

配置后，您可以在OpenCode中使用Vikunja工具：

list my vikunja projects

create a project called "My Tasks" with color #FF5733

add a task titled "Buy groceries" to project "My Tasks" with priority 3

show me all tasks in the Inbox project

发展

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev

# Run tests (when available)
npm test

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

贡献

欢迎投稿！请打开问题或拉取请求。

工具	说明
`add_task_label`	为任务添加标签
`remove_task_label`	从任务中删除标签
`list_task_labels`	列出任务上的所有标签
`list_labels`	列出所有可用标签（全球）

工具	说明
`list_comments`	列出任务的所有评论
`create_comment`	向任务添加注释
`update_comment`	更新评论
`delete_comment`	删除评论

使用说明

Vikunja MCP服务器

快速开始

特性

可用工具

项目

任务

任务状态和运动

受托人

标签

评论

关系

子任务

附件

工具参考

参数类型

项目

list_项目

get_工程

创建项目

update_项目

删除项目

列表_项目_儿童

move_项目

任务

list_tasks

list_project_tasks

获取任务

创建任务

update_task

删除任务

任务状态和运动

完成任务

重新打开任务

移动任务

受托人

add_task_assignee

remove_task_assignee

list_task_任务分配者

标签

add_task_label

移除任务标签

list_task_labels

list_labels

评论

list_注释

创建注释

更新_注释

删除注释

关系

创建关系

删除相关信息

list_task_relations

子任务

create_subtask

list_子任务

附件

列表任务附件

删除任务附件

例子

列出项目和任务

创建项目和任务

管理任务状态

与受让人合作

评论

关系

使用字符串ID

安装

先决条件

获取Vikunja API代币

从源代码构建

OpenCode配置

选项1：使用npx（推荐）

选项2：从源代码构建

配置选项

环境变量

Claude Code桌面应用程序配置

选项1：使用npx（推荐）

选项2：从源代码构建

配置选项