AI导哈

任务管理协议服务器

Vikunja MCP Server是一个基于MCP协议的服务，为Claude.ai提供直接访问Vikunja任务管理数据的功能，支持任务、评论、标签、项目等多种操作。

  • by Jacob-Tate
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 Jacob-Tate/vikunja-mcp

使用说明

Vikunja MCP服务器

一 MCP（模型上下文协议） 允许Claude.ai直接访问您的 维昆亚 任务管理数据。

特性

  • 42工具 涵盖任务、评论、标签、项目、团队、用户、视图和已保存的筛选器
  • OAuth 2.0 与Claude.ai的MCP集成兼容的身份验证
  • 单用户 设计-您的Vikunja API令牌是通过环境变量配置的，从不存储在MCP令牌中
  • 无状态HTTP 运输与 StreamableHTTPServerTransport

可用工具

组 工具
任务 get-tasks, get-task, create-task, update-task, delete-task, mark-task-done, bulk-update-tasks, get-task-assignees, set-task-assignees
评论 get-comments, create-comment, update-comment, delete-comment
标签 get-labels, create-label, update-label, delete-label, add-label-to-task, remove-label-from-task
项目 get-projects, get-project, create-project, update-project, delete-project, duplicate-project
团队 get-teams, get-team, create-team, update-team, delete-team, add-team-member, remove-team-member
用户 get-current-user, get-users
浏览次数 get-views, create-view, update-view, delete-view
过滤器 get-filter, create-filter, update-filter, delete-filter

示例提示

连接后，您可以问Claude以下问题：

任务

  • “显示我所有过期的任务”
  • 在后端项目中创建一个名为“审查PR#42”的任务，该任务将于周五到期，具有高优先级
  • “将“完成”桶中的所有任务标记为已完成”
  • “将分配给我的优先级≥3的所有任务移至列表顶部”

项目与组织

  • “列出我的所有活动项目”
  • “创建一个名为‘Q2 Planning’的蓝色新项目”
  • “移动项目中哪些任务仍处于打开状态？”

标签和团队

  • “将'bug'标签添加到任务#123”
  • “显示工程团队的所有成员”
  • “创建一个名为“已阻止”的红色标签”

评论与协作

  • “在任务#45中添加评论，说明PR已准备好进行审查”
  • “显示任务#99的所有评论”

Docker快速入门

docker run -d \
  -p 3000:3000 \
  -v vikunja-mcp-data:/app/data \
  -e VIKUNJA_API_URL=https://your-vikunja-instance.com \
  -e VIKUNJA_API_TOKEN=your-api-token \
  -e MCP_AUTH_PASSWORD=choose-a-strong-password \
  -e JWT_SECRET=$(openssl rand -hex 32) \
  -e BASE_URL=https://your-mcp-domain.com \
  ghcr.io/jacob-tate/vikunja-mcp:latest

或者使用Docker Compose——请参阅 docker-compose.yml.

连接到Claude.ai

  1. 在Claude.ai中，请访问 设置→ 集成→ 添加MCP服务器
  2. 请输入您的服务器URL： https://your-mcp-domain.com/mcp
  3. 浏览器弹出窗口将打开——输入您的 MCP_AUTH_PASSWORD
  4. 完成--克劳德现在可以访问您的Vikunja数据

环境变量

变量 必填 描述
VIKUNJA_API_URL ✅ Vikunja实例的URL
VIKUNJA_API_TOKEN ✅ 来自Vikunja的API令牌→ 设置→ API令牌
MCP_AUTH_PASSWORD ✅ OAuth浏览器弹出窗口中显示的密码
JWT_SECRET ✅ 签名令牌的随机字符串≥32个字符
BASE_URL ✅ 此MCP服务器的公共HTTPS URL
PORT -- HTTP端口（默认值： 3000)
AUTH_DB_PATH -- OAuth令牌的SQLite数据库（默认值： ./data/auth.db)

生成Vikunja API令牌

在维昆贾： 设置→ API令牌→ 创建令牌

给它一个描述性的名称（例如“Claude MCP”），并设置一个适当的到期日。授予它你希望克劳德拥有的权限。

不使用Docker运行

需要 Node.js 22 (better-sqlite3 无法在Node 24上编译）。

nvm use 22
npm install
cp .env.example .env
# edit .env with your values
npm run build
npm start

开发（热重新加载）：

npm run dev

备注：不要跑 npm run typecheck --MCP SDK的类型定义超过了Node的堆限制。 使用 npm run build （esbuild，~6ms）验证代码是否编译。

令牌撤销

要立即使令牌无效，请执行以下操作：

# Revoke an access token (JWT)
curl -X POST https://your-mcp-domain.com/revoke \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=<access_token>"

# Revoke a refresh token (UUID)
curl -X POST https://your-mcp-domain.com/revoke \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=<refresh_token>"

总是回来 200 OK 每 RFC 7009.

要一次使所有令牌无效，请执行以下操作： 旋转 JWT_SECRET 在 .env 并重新启动。

部署说明

  • 使用HTTPS暴露反向代理（nginx、Caddy）后面的端口3000
  • BASE_URL 必须是公共HTTPS URL——Claude.ai要求OAuth使用HTTPS
  • OAuth令牌在SQLite中持久化(./data/auth.db)--重新启动后仍能存活
  • 访问令牌在24小时后过期；刷新令牌持续90天，并自动轮换

项目结构

src/
├── config.ts              # Env var validation
├── index.ts               # Express app + startup
├── auth/
│   ├── db.ts              # SQLite singleton + schema init
│   ├── store.ts           # SQLite-backed OAuth state (tokens, clients)
│   ├── oauth.ts           # OAuthServerProvider + login form
│   └── middleware.ts      # Bearer token validation
├── vikunja/
│   └── client.ts          # axios-based Vikunja API client
└── mcp/
    ├── server.ts
    └── tools/
        ├── tasks.ts
        ├── comments.ts
        ├── labels.ts
        ├── projects.ts
        ├── teams.ts
        ├── users.ts
        ├── views.ts
        └── filters.ts

相关 MCP