内容
# vikunja-mcp
MCP 服务器，为 Claude 提供对您的 [Vikunja](https://vikunja.io) 任务管理实例的完全访问权限。
与 **任何 Vikunja 实例** 兼容 — 自托管、云端或 [Factumerit](https://factumerit.com)。
## 功能
- **多实例支持** — 连接多个 Vikunja 账户（个人、工作等）
- **强大的查询** — "什么逾期了？", "专注模式", "本周到期"
- **X-Q（交换队列）** — 在 Claude Desktop 和 Claude Code 之间传递任务
- **完整的 Vikunja API** — 项目、任务、标签、看板、关系
## 快速入门（Factumerit 用户）
如果您正在使用 Factumerit 的托管 Vikunja，设置是自动的：
1. 您的欢迎电子邮件中包含完整的配置 — 只需复制它
2. 粘贴到您的 Claude Desktop 配置文件（参见 [配置文件位置](#配置文件位置)）
3. [重启 Claude Desktop](#重启-claude-desktop)
4. 问 Claude： *"我的待办事项列表是什么？"*
## 手动设置
### 1. 安装 uv
[uv](https://docs.astral.sh/uv/) 是一个快速的 Python 包管理器。安装它：
**macOS / Linux：**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
**Windows (PowerShell)：**
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
### 2. 获取您的 Vikunja API 令牌
**简单方法（Factumerit）：**
登录 [mcp.factumerit.app](https://mcp.factumerit.app)，注册您的机器人，并通过电子邮件获取您的令牌。（需要 Beta 注册令牌 — [加入等待列表](https://mcp.factumerit.app/waiting-list?source=github) 如果您没有一个）
**自托管方法：**
前往您的 Vikunja 实例 → **设置** → **API 令牌** → **创建令牌**。给它一个名称（例如“Claude Desktop”）并授予所有权限。
### 3. 配置 Claude Desktop
添加到您的 Claude Desktop 配置文件：
**单个实例：**
```json
{
"mcpServers": {
"vikunja": {
"command": "uvx",
"args": ["vikunja-mcp@latest"],
"env": {
"VIKUNJA_URL": "https://your-vikunja-instance.com",
"VIKUNJA_TOKEN": "your-api-token"
}
}
}
}
```
**多个实例：**
```json
{
"mcpServers": {
"vikunja": {
"command": "uvx",
"args": ["vikunja-mcp@latest"],
"env": {
"VIKUNJA_INSTANCES": "[{\"name\": \"personal\", \"url\": \"https://vikunja.example.com\", \"token\": \"tk_xxx\"}, {\"name\": \"work\", \"url\": \"https://app.vikunja.cloud\", \"token\": \"tk_yyy\"}]",
"VIKUNJA_DEFAULT_INSTANCE": "personal"
}
}
}
}
```
> **提示：** 使用 `vikunja-mcp@latest` 始终获取最新版本。
### 配置文件位置
| 操作系统 | 路径 |
|----|------|
| **macOS** | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| **Windows** | `%APPDATA%\Claude\claude_desktop_config.json` |
| **Linux** | `~/.config/claude/claude_desktop_config.json` |
**提示：** 如果文件不存在，请使用上述配置创建它。
### 4. 重启 Claude Desktop
**macOS：** Cmd+Q，然后重新打开
**Windows：** 任意：
- 关闭 Claude，打开任务管理器（Ctrl+Shift+Esc），结束任何“Claude”进程，重新打开
- 或运行：`uv cache prune` 然后重新打开 Claude
**Linux：** 关闭并重新打开应用程序
### 5. 测试
问 Claude：
> "我有哪些项目在 Vikunja 中？"
如果有效，您将看到您的项目列表！
## 可用工具
### 强大的查询（快速）
- `focus_now` — 高优先级 + 逾期任务（最适合“应该关注什么？”）
- `due_today` — 今日到期 + 逾期任务
- `due_this_week` — 7 天内到期任务
- `overdue_tasks` — 仅逾期任务
- `high_priority_tasks` — 优先级 3+ 任务
- `urgent_tasks` — 优先级 4+（关键）任务
- `unscheduled_tasks` — 无到期日期任务
- `task_summary` — 快速统计（无任务详情）
### 实例管理
- `list_instances` — 显示所有配置实例
- `switch_instance` — 更改活动实例
- `get_active_context` / `set_active_context` — 获取/设置默认实例
### 项目
- `list_projects` — 列出所有项目
- `get_project` — 获取项目详情
- `create_project` — 创建新项目
- `delete_project` — 删除项目
### 任务
- `list_tasks` — 列出任务（带筛选）
- `get_task` — 获取任务详情，包含标签/分配者
- `create_task` — 创建任务，包含标题、描述、到期日期、优先级
- `update_task` — 更新任务字段
- `complete_task` — 将任务标记为完成
- `delete_task` — 删除任务
- `set_task_position` — 将任务移动到看板桶
- `add_label_to_task` — 将标签附加到任务
- `assign_user` / `unassign_user` — 管理任务分配
### 标签
- `list_labels` — 列出所有标签
- `create_label` — 创建新标签，包含颜色
- `delete_label` — 删除标签
### 看板
- `get_kanban_view` — 获取项目看板视图 ID
- `list_buckets` — 列出看板列
- `create_bucket` — 创建新看板列
### 视图
- `list_views` — 列出项目视图
- `create_view` — 创建列表/看板/甘特/表格视图
- `get_view_tasks` — 通过特定视图获取任务
### 关系
- `create_task_relation` — 链接任务（阻塞、子任务等）
- `list_task_relations` — 列出任务依赖关系
### X-Q（交换队列）
- `check_xq` — 检查待处理交接项目
- `setup_xq` — 初始化 X-Q 项目，包含适当桶
- `claim_xq_task` — 认领任务进行处理
- `complete_xq_task` — 将任务标记为已归档并发送到目的地
## 使用示例
配置完成后，只需询问 Claude：
- *"什么需要我的关注？"* （使用 focus_now）
- *"本周到期的是什么？*
- *"显示我本周所有到期的任务"*
- *"在工作项目中创建一个审查 Q4 报告的任务"*
- *"是什么阻塞了网站重新设计任务？"*
- *"将 'Fix login bug' 任务移动到完成列"*
- *"切换到我的工作实例"*
- *"列出所有项目中的高优先级任务"*
## 高级配置
对于高级用户，vikunja-mcp 支持在 `~/.vikunja-mcp/config.yaml` 处使用 YAML 配置文件，以实现附加功能。
### X-Q（交换队列）设置
X-Q 允许您在 Claude Desktop 和 Claude Code 之间传递任务。要启用：
1. 在您的 Vikunja 实例中创建一个 X-Q 项目
2. 将项目 ID 添加到您的配置：
```yaml
# ~/.vikunja-mcp/config.yaml
xq:
personal: 47 # 个人实例的 X-Q 项目 ID
work: 14915 # 工作实例的 X-Q 项目 ID
instances:
personal:
url: https://vikunja.example.com
token: tk_xxx
admin: true # setup_xq 工具所需
work:
url: https://app.vikunja.cloud
token: tk_yyy
admin: true
```
3. 使用 `setup_xq` 创建标准桶（📬 交接，🔍 审查，✅ 已归档）
### 项目配置
存储每个项目的设置，例如默认桶和排序策略：
```yaml
projects:
'47':
instance: personal
name: X-Q
default_bucket: 📬 交接
'123':
instance: work
name: 冲刺看板
sort_strategy:
default: due_date
buckets:
"In Progress": start_date
```
## 故障排除
### "未找到 MCP 服务器" 或工具未出现
1. 检查您的配置文件语法（有效的 JSON 吗？）
2. 确保 `uv` 已安装并在您的 PATH 中
3. 完全重启 Claude Desktop（参见上文）
### "VIKUNJA_URL 和 VIKUNJA_TOKEN 环境变量是必需的"
您的配置缺少 `env` 部分。请确保它如下所示：
```json
"env": {
"VIKUNJA_URL": "https://...",
"VIKUNJA_TOKEN": "tk_..."
}
```
### "401 未授权" 错误
您的 API 令牌可能已过期或被吊销。在 Vikunja 设置 → API 令牌中创建一个新的令牌。
### Windows：Claude 无法正确重启
使用任务管理器（Ctrl+Shift+Esc）确保在重新打开之前所有 Claude 进程都已结束。或运行 `uv cache prune` 以清除缓存环境。
### 未获取最新版本
在参数中使用 `vikunja-mcp@latest`，并在关闭 Claude Desktop 后运行 `uv cache prune`。
## 要求
- Python 3.10+（由 uv 自动安装）
- 具有 API 访问权限的 Vikunja 实例
- Claude Desktop（或任何 MCP 兼容客户端）
## 链接
- [Vikunja](https://vikunja.io) — 开源待办事项应用
- [Factumerit](https://factumerit.com) — 具有 AI 功能的托管 Vikunja
- [MCP 协议](https://modelcontextprotocol.io) — 模型上下文协议
- [uv](https://docs.astral.sh/uv/) — 快速 Python 包管理器
## 许可证
MIT
