Cristoslc MCP

vk——Vikunja命令行界面和MCP服务器

一个统一的Python库，用于与 维昆亚 实例，通过三个适配器公开：CLI(vk)，MCP stdio服务器和MCP HTTP/SSE服务器。这三者共享一个核心，该核心拥有Vikunja API通信、域逻辑和输出格式。

为什么

Vikunja是一个自托管的开源任务管理平台，具有干净的REST API，没有速率限制。但它没有官方的CLI，也没有MCP服务器。 vk 用一个代码库填补了这两个空白，使人类（通过终端）和人工智能代理（通过MCP）都可以完全访问Vikunja。

安装

# With uv (recommended)
uv tool install git+https://github.com/cristoslc/vk.git

# From source
git clone https://github.com/cristoslc/vk.git
cd vk
uv sync

需要Python 3.11+。

快速开始

# Configure (writes .vk-config.json)
vk auth login --url http://localhost:3456 --token tk_your_api_token

# Check connection
vk auth status

# List projects
vk project list

# Create a task
vk task create --title "Buy groceries" --project "Household Tasks" --bucket "Incoming"

# Move a task between Eisenhower buckets
vk task move 42 --bucket "Do Now"

# Search
vk search "electric bill"

# JSON output (all commands)
vk task list "Household Tasks" --json

命令

vk auth login [--url URL] [--token TOKEN]     # Configure authentication
vk auth status                                 # Check connection

vk project list [--json]                       # List all projects
vk project create --title TITLE [--json]       # Create a project
vk project get ID [--json]                     # Get project details

vk bucket list PROJECT [--view VIEW] [--json]  # List kanban buckets
vk bucket create PROJECT --title T [--json]    # Create a bucket

vk task list [PROJECT] [--bucket B] [--json]   # List tasks
vk task get ID [--json]                        # Get a task
vk task create --title T --project P [--json]  # Create a task
vk task update ID [--title T] [--done] [--json]# Update a task
vk task move ID --bucket B [--json]            # Move to bucket
vk task delete ID [--force]                    # Delete a task

vk comment list TASK [--json]                  # List comments
vk comment add TASK --text TEXT [--json]        # Add a comment

vk attach list TASK [--json]                   # List attachments
vk attach add TASK --file PATH [--json]         # Upload attachment
vk attach get TASK ATTACH_ID [--output PATH]    # Download attachment

vk search QUERY [--project P] [--json]          # Search tasks

vk label list [--json]                          # List labels
vk label create --title T [--color HEX] [--json]# Create a label

vk mcp stdio                                    # MCP server (stdio)
vk mcp http [--port 8456]                        # MCP server (HTTP/SSE)

MCP集成

克劳德代码（stdio）

添加到您的 .mcp.json:

{
  "mcpServers": {
    "vk": {
      "command": "vk",
      "args": ["mcp", "stdio"],
      "env": {
        "VK_URL": "http://localhost:3456",
        "VK_TOKEN": "tk_your_token"
      }
    }
  }
}

HTTP/SSE

vk mcp http --port 8456

连接到 http://localhost:8456/sse 消息端点位于 /messages/.

可用的MCP工具

18个工具镜像CLI界面： vk_task_list, vk_task_create, vk_task_update, vk_task_move, vk_task_get, vk_task_delete, vk_project_list, vk_project_create, vk_project_get, vk_bucket_list, vk_bucket_create, vk_comment_list, vk_comment_add, vk_attach_list, vk_attach_add, vk_search, vk_label_list, vk_label_create.

配置

代币解析顺序（最高获胜）：

1. --token 标志/显式参数
2. VK_TOKEN 环境变量
3. .vk-config.json 在当前目录中（向上走到git根目录）
4. ~/.config/vk/config.json

配置文件格式：

{
  "url": "http://localhost:3456",
  "token": "tk_...",
  "default_project": "Household Tasks",
  "kanban_view": "Kanban"
}

建筑

六边形架构——三个适配器共享一个核心：

         CLI (Click)    MCP (stdio)    MCP (HTTP/SSE)
              \              |              /
               \             |             /
                +-------Core Services------+
                |  tasks, projects, buckets |
                |  comments, attachments    |
                |  search, labels, auth     |
                +----------+---------------+
                           |
                    Vikunja HTTP Client
                           |
                    Vikunja REST API

• 核心服务 接受并返回类型化域对象（数据类），而不是原始JSON
• 名称解析 通过本地缓存将人名（“家庭任务”）映射到ID
• 分页 由HTTP客户端透明地处理

发展

git clone https://github.com/cristoslc/vk.git
cd vk
uv sync
uv run pytest               # 47 tests
uv run vk --help

许可证

麻省理工学院