Vikunja MCP Server

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）管理

可用工具

项目

任务

任务状态和运动

受托人

标签

评论

关系

子任务

附件

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

工具参考

参数类型

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

备注：所有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

标签

add_task_label

为任务添加标签。

• 参数:

- taskId （数字，必填）：任务ID - label_id （数字，必填）：要添加的标签ID

移除任务标签

从任务中删除标签。

• 参数:

- taskId （数字，必填）：任务ID - label_id （数字，必填）：要删除的标签ID

list_task_labels

列出任务上的所有标签。

• 参数:

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

list_labels

列出所有可用标签（全局）。

• 参数：无需
• 可选的:

- project_id （编号）：按项目ID筛选 - page （编号）：页码 - per_page （数量）：每页项目数

评论

list_注释

列出任务的所有注释。

• 参数:

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

• 可选的:

- page （编号）：页码 - per_page （数量）：每页项目数

创建注释

向任务添加注释。

• 参数:

- taskId （数字，必填）：任务ID - comment （string，必填）：评论文本

更新_注释

更新评论。

• 参数:

- taskId （数字，必填）：任务ID - commentId （数字，必填）：评论ID - comment （字符串，必填）：新注释文本

删除注释

删除评论。

• 参数:

- taskId （数字，必填）：任务ID - commentId （数字，必填）：要删除的评论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代币

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

从源代码构建

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",
      },
    },
  },
}

配置选项

环境变量

您还可以在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",
      },
    },
  },
}

配置选项

环境变量

您还可以在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服务器配置的不同作用域：

# 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

配置选项

环境变量

您还可以在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选项

使用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许可证-有关详细信息，请参阅许可证文件。

贡献

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