使用说明

MCP Vikunja

用于Vikunja任务管理集成的模型上下文协议（MCP）服务器，支持stdio和HTTP传输。

概述

该项目提供了一个MCP服务器，允许LLM和AI助手通过标准化的工具调用与Vikunja任务管理进行交互。它支持本地CLI使用（stdio）和远程web部署（HTTP）。

特性

📋 列出Vikunja项目和视图中的任务
🔍 获取包括铲斗放置在内的详细任务信息
📦 列出项目桶并组织任务
🏗️ 列出所有可用项目
🚀 多种传输模式：stdio（CLI）和HTTP（web）
🔧 具有会话管理的可配置HTTP服务器
✅ 使用官方MCP Go SDK构建

安装

go get github.com/meschbach/mcp-vikunja

快速开始

1.构建服务器

go build -o bin/mcp-vikunja ./cmd/mcp-vikunja

2.配置Vikunja连接

export VIKUNJA_HOST="https://your-vikunja-instance.com"
export VIKUNJA_TOKEN="your-api-token"

3.运行服务器

MCP服务器现在为不同的传输模式使用显式子命令：

选项A:Stdio传输（用于本地CLI工具）

# Default Markdown output (recommended for AI/LLMs)
./bin/mcp-vikunja stdio

# JSON output (for legacy compatibility)
./bin/mcp-vikunja stdio --output-format json

# Both formats together  
./bin/mcp-vikunja stdio -o both

# Environment variable setting
VIKUNJA_OUTPUT_FORMAT=json ./bin/mcp-vikunja stdio

选项B:HTTP传输（用于web应用程序和远程访问）

# Default Markdown output (recommended for AI/LLMs)
./bin/mcp-vikunja server

# JSON output (for legacy compatibility)
./bin/mcp-vikunja server --output-format json

选项C：显示帮助

./bin/mcp-vikunja
# Shows available commands and usage examples

运输方式

标准输入输出传输

最佳：本地CLI工具、开发环境
用法: ./bin/mcp-vikunja stdio
特性：通过标准I/O进行通信
示例: VIKUNJA_HOST=https://example.com VIKUNJA_TOKEN=token ./bin/mcp-vikunja stdio

HTTP传输

最佳：Web应用程序、远程访问、多个客户端
用法: ./bin/mcp-vikunja server
特性：会话管理、并发连接、流式HTTP
示例: VIKUNJA_HOST=https://example.com VIKUNJA_TOKEN=token ./bin/mcp-vikunja server --http-port 9000

CLI命令

MCP服务器提供了一个丰富的命令行界面：

服务器命令

mcp-vikunja server -启动HTTP+流式传输服务器
mcp-vikunja stdio -启动stdio传输服务器

配置命令

mcp-vikunja config show -显示当前配置
mcp-vikunja config validate -验证配置和测试连接

实用程序命令

mcp-vikunja health -测试Vikunja连接
mcp-vikunja version -显示版本和构建信息
mcp-vikunja help -显示全面帮助

示例

# Start HTTP server with custom settings
./bin/mcp-vikunja server --http-host 0.0.0.0 --http-port 9000 --stateless

# Start stdio server with verbose logging
./bin/mcp-vikunja stdio --verbose --vikunja-host https://example.com

# Show current configuration
./bin/mcp-vikunja config show --format json

# Validate configuration
./bin/mcp-vikunja config validate

# Test Vikunja connectivity
./bin/mcp-vikunja health --vikunja-host https://example.com --vikunja-token token

配置

所需的环境变量

VIKUNJA_HOST -您的Vikunja实例URL
VIKUNJA_TOKEN -您的Vikunja API代币

可选输出格式配置

变量/标志	默认值	描述
`VIKUNJA_OUTPUT_FORMAT`	`markdown`	输出格式：json、markdown，两者都有
`--output-format` / `-o`	`markdown`	覆盖VIKUNJA_OUTPUT_FORMAT的CLI标志

输出格式优先级：CLI标志>环境变量>默认值（markdown）

输出格式选项:

json -原始JSON输出（用于传统兼容性）
markdown -人类可读的Markdown输出，带有表格和格式（建议用于AI/LLM）
both -JSON和Markdown组合输出

可选HTTP配置

变量	默认值	描述
`MCP_TRANSPORT`	`stdio`	运输类型： `stdio` 或 `http`
`MCP_HTTP_HOST`	`localhost`	服务器绑定地址
`MCP_HTTP_PORT`	`8080`	服务器端口
`MCP_HTTP_SESSION_TIMEOUT`	`30m`	会话超时
`MCP_HTTP_STATELESS`	`false`	禁用会话跟踪

可用工具

服务器提供以下MCP工具：

list_tasks -使用筛选选项列出项目中的任务
get_task -获取包括铲斗放置在内的详细任务信息
list_buckets -在项目视图中列出所有桶（默认为收件箱项目和看板视图）
list_projects -列出所有可用项目
create_task -创建带有标题、描述、项目、bucket和截止日期的新任务

独立CLI工具

除了MCP服务器外，该存储库还包括一个用于直接Vikunja交互的独立CLI工具：

安装

# Build the CLI tool
go build -o bin/vikunja-cli ./cmd/vikunja-cli

# Or install directly
go install ./cmd/vikunja-cli

配置

CLI工具使用与MCP服务器相同的环境变量：

VIKUNJA_HOST -您的Vikunja实例URL（必填）
VIKUNJA_TOKEN -您的Vikunja API令牌（必需）
VIKUNJA_INSECURE -跳过TLS验证（可选，默认值：false）

或者使用命令行标志覆盖环境变量。

可用命令

# Show help
vikunja-cli --help

# List all tasks (optionally filtered by project)
vikunja-cli tasks list [--project <id>]

# Get detailed task information
vikunja-cli tasks get <task-id>

# Create a new task
vikunja-cli tasks create <title> [description] [flags]

创建任务

这 tasks create 命令通过灵活的项目和bucket分配创建新任务：

# Create task with title only (uses default "Inbox" project)
vikunja-cli tasks create "My new task"

# Create task with title and description
vikunja-cli tasks create "My task" "Detailed description"

# Create task in specific project by ID
vikunja-cli tasks create "Task" --project 123

# Create task in project by title
vikunja-cli tasks create "Task" --project "Work Projects"

# Create task in specific bucket by ID
vikunja-cli tasks create "Task" --project 123 --bucket 456

# Create task in bucket by title (requires project to have Kanban view)
vikunja-cli tasks create "Task" --project 123 --bucket "In Progress"

# Use default Inbox with bucket by title
vikunja-cli tasks create "Task" --bucket "In Progress"

输出格式化

CLI工具支持多种输出格式：

# Table output (default)
vikunja-cli tasks create "Task" --project 123

# JSON output
vikunja-cli tasks create "Task" --project 123 --json

# Markdown output
vikunja-cli tasks create "Task" --project 123 --markdown

# Write output to file
vikunja-cli tasks create "Task" --project 123 --output task.json

# Disable colors
vikunja-cli tasks create "Task" --no-color

# Verbose logging
vikunja-cli tasks create "Task" --verbose

通用标志

--host / -h -Vikunja实例主机名（覆盖Vikunja_HOST）
--token / -t -API令牌（替代VIKUNJA_token）
--insecure / -k -跳过TLS证书验证
--json / -j -输出为JSON
--markdown / -m -输出为Markdown
--output / -o -将输出写入文件
--verbose / -v -启用调试日志记录
--no-color -禁用彩色输出

示例用法

使用cURL（HTTP传输）进行测试

# Start server with HTTP transport
VIKUNJA_HOST=https://example.com VIKUNJA_TOKEN=your-token ./bin/mcp-vikunja server &

# Test the server
curl -X POST http://localhost:8080 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
  }'

Docker部署

FROM golang:1.23-alpine AS builder
WORKDIR /app
COPY . .
RUN go build -o mcp-vikunja ./cmd/mcp-vikunja

FROM alpine:latest
RUN apk --no-cache add ca-certificates
WORKDIR /root/
COPY --from=builder /app/mcp-vikunja .
CMD ["./mcp-vikunja"]

# Build and run with Docker
docker build -t mcp-vikunja .
docker run -p 8080:8080 \
  -e VIKUNJA_HOST=https://your-vikunja.com \
  -e VIKUNJA_TOKEN=your-token \
  mcp-vikunja server --http-host 0.0.0.0

发展

看代理商.md 用于编码指南和命令。

地方发展指挥部

# Full setup: build, start services, run tests
make dev

# Individual commands
make build          # Build release binaries
make dev-up         # Start docker-compose services
make dev-down       # Stop services
make setup-user     # Create Vikunja user and API token

# Quality checks
make check          # Run all checks: fmt, vet, lint, tidy, test, coverage, build
make fmt            # Format code
make vet            # Run go vet
make lint           # Run golangci-lint
make tidy-check     # Verify go mod tidy produces no changes
make test           # Run tests with verbose output
make test-cover     # Run tests with coverage report

测试

# Run tests (requires docker-compose: make dev-up && make setup-user)
make test

# Run with coverage
make test-cover

文档

Docker编写指南 -使用Docker进行本地开发设置
运输配置指南 -详细的传输设置和部署选项
代理商.md -开发指南和项目标准

许可证

麻省理工学院