Vikunja MCP服务器
用于管理Vikunja项目和任务的模型上下文协议服务器。
快速开始
直接使用npx运行(无需安装):```bash
npx vikunja-mcp --token YOUR_VIKUNJA_TOKEN
使用自定义Vikunja URL:```bash
npx vikunja-mcp --url https://your-vikunja.com/api/v1 --token YOUR_TOKEN
或者使用环境变量:```bash
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` |列出任务的所有指定人员|
### 标签
|工具|说明|
| ------------------- | ------------------------------------ |
| `add_task_label` |为任务添加标签|
| `remove_task_label` |从任务中删除标签|
| `list_task_labels` |列出任务上的所有标签|
| `list_labels` |列出所有可用标签(全球)|
### 评论
|工具|说明|
| ---------------- | ---------------------------- |
| `list_comments` |列出任务的所有评论|
| `create_comment` |向任务添加注释|
| `update_comment` |更新评论|
| `delete_comment` |删除评论|
### 关系
|工具|说明|
| --------------------- | ----------------------------------- |
| `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
### 标签
#### 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代币
- 登录您的Vikunja实例
- 前往设置→ API令牌
- 创建新令牌
从源代码构建```bash
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`):```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,请从源代码构建:```bash
git clone https://github.com/Wosh-i/vikunja-mcp.git
cd vikunja-mcp
npm install
npm run build
然后配置OpenCode:```jsonc
{
"$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中全局设置环境变量:```bash
export VIKUNJA_URL="https://your-vikunja-instance.com/api/v1"
export VIKUNJA_TOKEN="your-api-token-here"
然后OpenCode配置可以更简单:```jsonc
{
"$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````jsonc
{
"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,请从源代码构建:```bash
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````jsonc
{
"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中全局设置环境变量:```bash
export VIKUNJA_URL="https://your-vikunja-instance.com/api/v1"
export VIKUNJA_TOKEN="your-api-token-here"
那么Claude Code配置可以更简单:```jsonc
{
"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:```bash
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,请从源代码构建:```bash
git clone https://github.com/Wosh-i/vikunja-mcp.git
cd vikunja-mcp
npm install
npm run build
然后配置克劳德代码:```bash
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服务器```bash
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中全局设置环境变量:```bash
export VIKUNJA_URL="https://your-vikunja-instance.com/api/v1"
export VIKUNJA_TOKEN="your-api-token-here"
然后配置更简单:```bash
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
发展```bash
Install dependencies
npm install
Build
npm run build
Run in development mode
npm run dev
Run tests (when available)
npm test
```
许可证
MIT许可证-有关详细信息,请参阅许可证文件。
贡献
欢迎投稿!请打开问题或拉取请求。
