{"_id":"@aimbitgmbh/vikunja-mcp","_rev":"3-bdda751482e1cfe067a178585eaa91e9","name":"@aimbitgmbh/vikunja-mcp","dist-tags":{"latest":"1.0.1"},"versions":{"0.1.0":{"name":"@aimbitgmbh/vikunja-mcp","version":"0.1.0","keywords":["mcp","model-context-protocol","llm","ai-assistant","ai-integration","vikunja","tasks","todo","productivity","task-management","project-management","kanban","collaboration"],"author":{"url":"https://aimbit.de","name":"aimbit GmbH","email":"info@aimbit.de"},"license":"MIT","_id":"@aimbitgmbh/vikunja-mcp@0.1.0","maintainers":[{"name":"aimbit-ni","email":"ni@aimbit.de"}],"homepage":"https://github.com/aimbitgmbh/vikunja-mcp","bugs":{"url":"https://github.com/aimbitgmbh/vikunja-mcp/issues","email":"info@aimbit.de"},"bin":{"vikunja-mcp":"dist/index.js"},"dist":{"shasum":"0738f7b381019e42649f73ddbee3e7f16ccd6e11","tarball":"https://registry.npmjs.org/@aimbitgmbh/vikunja-mcp/-/vikunja-mcp-0.1.0.tgz","fileCount":84,"integrity":"sha512-Vgu9BZg6p6g1/8XJUZsAShkP8DbLmocKjkt5VK7xEogjDBd9j0Wrs31AmPcH0LwTOCAoEUHnBMXCUt0wb+NBGw==","signatures":[{"sig":"MEQCIBiQOE8rglX5IrxE6QYQCEVwBO97le8q3F8mqoCZJ1SdAiAtwHEsdjkFyVZi2TD4rX88heJtgysm/SXGWxd5U/Zbrw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":825602},"main":"dist/index.js","type":"commonjs","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"eeb0713f8bd68addbfa7bc50cfd0000b3c7ff289","scripts":{"dev":"tsx --import dotenv/config src/index.ts","build":"tsc && chmod +x dist/index.js","clean":"rm -rf dist","inspector":"npx @modelcontextprotocol/inspector tsx src/index.ts","prepublishOnly":"npm run build"},"_npmUser":{"name":"aimbit-ni","email":"ni@aimbit.de"},"repository":{"url":"git+https://github.com/aimbitgmbh/vikunja-mcp.git","type":"git"},"_npmVersion":"10.8.2","description":"MCP server for Vikunja task management","directories":{},"_nodeVersion":"20.19.6","dependencies":{"zod":"^4.3.4","dotenv":"^16.4.7","@modelcontextprotocol/sdk":"^1.25.1"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.21.0","ts-node":"^10.9.2","typescript":"^5.9.3","@types/node":"^25.0.3"},"_npmOperationalInternal":{"tmp":"tmp/vikunja-mcp_0.1.0_1767898244838_0.21038130880266426","host":"s3://npm-registry-packages-npm-production"}},"1.0.0":{"name":"@aimbitgmbh/vikunja-mcp","version":"1.0.0","keywords":["mcp","model-context-protocol","llm","ai-assistant","ai-integration","vikunja","vikunja-mcp","mcp-server","vikunja-api-v2","tasks","todo","productivity","task-management","project-management","kanban","collaboration"],"author":{"url":"https://aimbit.de","name":"aimbit GmbH","email":"info@aimbit.de"},"license":"MIT","_id":"@aimbitgmbh/vikunja-mcp@1.0.0","maintainers":[{"name":"aimbit-ni","email":"ni@aimbit.de"}],"homepage":"https://github.com/aimbitgmbh/vikunja-mcp","bugs":{"url":"https://github.com/aimbitgmbh/vikunja-mcp/issues","email":"info@aimbit.de"},"bin":{"vikunja-mcp":"dist/index.js"},"dist":{"shasum":"1abd58c216f273d8dfc3dc9f5950dce1317cbba9","tarball":"https://registry.npmjs.org/@aimbitgmbh/vikunja-mcp/-/vikunja-mcp-1.0.0.tgz","fileCount":49,"integrity":"sha512-aGNCfTlRQGG25Sh9i8WXKty8Ixy8WgKN9w3y5PbvcyDjEi9Vg7ketyUOmmJqJnRWbwbSxHD8u6NmJ80MtdKbWA==","signatures":[{"sig":"MEUCIG9Ec7VzgBwdr1RY1B/sJ9RyZDmdsUD83S20LeqXAE/cAiEAzbdWPw5oA62XoRyF8opIXLpNZQwZvfYYlnamxPbQxRE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":797104},"main":"dist/index.js","type":"commonjs","types":"dist/index.d.ts","engines":{"node":">=20.18.1"},"exports":{".":{"types":"./dist/index.d.ts","require":"./dist/index.js"}},"gitHead":"5d6142576eb0d6c33ac6094d9a92d28c1b8314ca","scripts":{"dev":"tsx --import dotenv/config src/index.ts","test":"tsx --test tests/*.test.ts","build":"npm run clean && tsc && chmod +x dist/index.js","check":"npm run typecheck && npm test","clean":"rm -rf dist","prepack":"npm run build","inspector":"npx @modelcontextprotocol/inspector tsx src/index.ts","test:live":"tsx scripts/live-smoke.ts","test:qwen":"tsx scripts/qwen-eval.ts","typecheck":"tsc --noEmit && tsc --project tsconfig.check.json"},"_npmUser":{"name":"aimbit-ni","email":"ni@aimbit.de"},"repository":{"url":"git+https://github.com/aimbitgmbh/vikunja-mcp.git","type":"git"},"_npmVersion":"10.8.2","description":"MCP server for Vikunja task management, project management, and Vikunja 2.6+ API v2","directories":{},"_nodeVersion":"20.19.6","dependencies":{"zod":"^4.5.4","dotenv":"^17.4.2","undici":"^7.29.0","@modelcontextprotocol/sdk":"^1.30.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"packageManager":"npm@10.8.2","devDependencies":{"tsx":"^4.23.13","typescript":"^5.9.3","@types/node":"^20.19.43"},"_npmOperationalInternal":{"tmp":"tmp/vikunja-mcp_1.0.0_1788348061589_0.8919768242903183","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"_id":"@aimbitgmbh/vikunja-mcp@1.0.1","bin":{"vikunja-mcp":"dist/index.js"},"bugs":{"url":"https://github.com/aimbitgmbh/vikunja-mcp/issues","email":"info@aimbit.de"},"dist":{"shasum":"d88eddffee262908a4e4848f05cfa44fe0f2a1cd","tarball":"https://registry.npmjs.org/@aimbitgmbh/vikunja-mcp/-/vikunja-mcp-1.0.1.tgz","fileCount":49,"integrity":"sha512-Mz9SkMgNDUwnw6txKu8qdhKIeu0rMtecu92KzbAPhV35K76zJ16wVd9jEWbjA2LNtDxj8ns+VCMcZuMxtaZJmQ==","signatures":[{"sig":"MEUCIDz+6mDDOb2L7EcQiQA5zC24VmKgB5xt6wO3ifO9q554AiEA9noq67Er/CJ5z9nsiygLM7LW8JviXtzHRpunh0+wkfo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC7MTYL3vnU1PmIHUzUrGa1arhIItIlZvpzLXnX81/vXwIgSTzB0wtghE/GdtUzWQvuVjUGUuhKmNp+l8a1rU4Xqkw="}],"unpackedSize":796767},"main":"dist/index.js","name":"@aimbitgmbh/vikunja-mcp","type":"commonjs","types":"dist/index.d.ts","author":{"url":"https://aimbit.de","name":"aimbit GmbH","email":"info@aimbit.de"},"engines":{"node":">=20.18.1"},"exports":{".":{"types":"./dist/index.d.ts","require":"./dist/index.js"}},"gitHead":"47158aa93331c48fb8b5f1be8897ff95219e6e43","license":"MIT","scripts":{"dev":"tsx --import dotenv/config src/index.ts","test":"tsx --test tests/*.test.ts","build":"npm run clean && tsc && chmod +x dist/index.js","check":"npm run typecheck && npm test","clean":"rm -rf dist","prepack":"npm run build","inspector":"npx @modelcontextprotocol/inspector tsx src/index.ts","test:live":"tsx scripts/live-smoke.ts","test:qwen":"tsx scripts/qwen-eval.ts","typecheck":"tsc --noEmit && tsc --project tsconfig.check.json"},"version":"1.0.1","_npmUser":{"name":"aimbit-ni","email":"ni@aimbit.de"},"homepage":"https://github.com/aimbitgmbh/vikunja-mcp","keywords":["mcp","model-context-protocol","llm","ai-assistant","ai-integration","vikunja","vikunja-mcp","mcp-server","vikunja-api-v2","tasks","todo","productivity","task-management","project-management","kanban","collaboration"],"repository":{"url":"git+https://github.com/aimbitgmbh/vikunja-mcp.git","type":"git"},"_npmVersion":"10.8.2","description":"MCP server for Vikunja task management, project management, and Vikunja 2.6+ API v2","directories":{},"maintainers":[{"name":"aimbit-ni","email":"ni@aimbit.de"}],"_nodeVersion":"20.19.6","dependencies":{"zod":"^4.5.4","dotenv":"^17.4.2","undici":"^7.30.0","@modelcontextprotocol/sdk":"^1.30.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"packageManager":"npm@10.8.2","devDependencies":{"tsx":"^4.23.13","typescript":"^5.9.3","@types/node":"^20.19.43"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/vikunja-mcp_1.0.1_1790768111267_0.8330651653961867"}}},"time":{"created":"2026-01-08T18:50:44.732Z","modified":"2026-09-30T11:35:11.543Z","0.1.0":"2026-01-08T18:50:44.979Z","1.0.0":"2026-09-02T11:21:01.730Z","1.0.1":"2026-09-30T11:35:11.370Z"},"bugs":{"url":"https://github.com/aimbitgmbh/vikunja-mcp/issues","email":"info@aimbit.de"},"author":{"url":"https://aimbit.de","name":"aimbit GmbH","email":"info@aimbit.de"},"license":"MIT","homepage":"https://github.com/aimbitgmbh/vikunja-mcp","keywords":["mcp","model-context-protocol","llm","ai-assistant","ai-integration","vikunja","vikunja-mcp","mcp-server","vikunja-api-v2","tasks","todo","productivity","task-management","project-management","kanban","collaboration"],"repository":{"url":"git+https://github.com/aimbitgmbh/vikunja-mcp.git","type":"git"},"description":"MCP server for Vikunja task management, project management, and Vikunja 2.6+ API v2","maintainers":[{"name":"aimbit-ni","email":"ni@aimbit.de"}],"readme":"# Vikunja MCP Server – MCP for Vikunja Task Management\n\n[![npm version](https://img.shields.io/npm/v/@aimbitgmbh/vikunja-mcp)](https://www.npmjs.com/package/@aimbitgmbh/vikunja-mcp)\n[![CI](https://github.com/aimbitgmbh/vikunja-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/aimbitgmbh/vikunja-mcp/actions/workflows/ci.yml)\n[![Vikunja 2.6+](https://img.shields.io/badge/Vikunja-2.6%2B-196aff)](https://vikunja.io/)\n[![Node.js 20.18+](https://img.shields.io/badge/Node.js-%E2%89%A520.18.1-43853d)](https://nodejs.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\nAn MCP server for Vikunja task management and project management. It connects AI assistants and other Model Context Protocol clients to Vikunja 2.6+ through the stable `/api/v2` API.\n\nVersion 1.0.0 is tested with **Qwen 3.8 27B** for reliable MCP tool selection. The server remains model-independent and works with any standards-compliant MCP client.\n\n## Features\n\n- 51 focused MCP tools with consistent plural resource names\n- Tasks, projects, labels, comments, assignees, relations, and bulk updates\n- Saved filters, notifications, project views, and kanban buckets\n- Server-side search, filtering, sorting, expansion, and pagination\n- Structured JSON results plus readable text for broad client compatibility\n- Destructive task, project, label, and notification deletion disabled by default\n- Vikunja API v2 contract validation and TypeScript input validation\n\n## Requirements\n\n- Node.js 20.18.1 or newer\n- Vikunja 2.6.0 or newer\n- A Vikunja API token with the permissions needed for the tools you use\n\nCreate a token in Vikunja under **Settings → API Tokens**. Prefer the narrowest permissions that cover your workflow.\n\n## Install and configure\n\nThe package can run directly through `npx`:\n\n```json\n{\n  \"mcpServers\": {\n    \"vikunja\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@aimbitgmbh/vikunja-mcp@1.0.1\"],\n      \"env\": {\n        \"VIKUNJA_URL\": \"https://vikunja.example.com\",\n        \"VIKUNJA_API_TOKEN\": \"your-api-token\"\n      }\n    }\n  }\n}\n```\n\n`VIKUNJA_URL` may be the instance root, `/api/v1`, or `/api/v2`; the server normalizes it to `/api/v2`.\n\nTo install it globally instead:\n\n```bash\nnpm install --global @aimbitgmbh/vikunja-mcp@1.0.1\nvikunja-mcp\n```\n\n## Configuration\n\n| Variable | Required | Default | Purpose |\n| --- | --- | --- | --- |\n| `VIKUNJA_URL` | Yes | — | Vikunja instance URL |\n| `VIKUNJA_API_TOKEN` | Yes | — | Vikunja API token |\n| `VERIFY_SSL` | No | `true` | Verify the TLS certificate |\n| `VIKUNJA_REQUEST_TIMEOUT_MS` | No | `30000` | HTTP timeout in milliseconds |\n| `ENABLE_TASK_DELETE` | No | `false` | Allow permanent task deletion |\n| `ENABLE_PROJECT_DELETE` | No | `false` | Allow permanent project deletion |\n| `ENABLE_LABEL_DELETE` | No | `false` | Allow permanent label deletion |\n| `ENABLE_NOTIFICATION_DELETE_ALL` | No | `false` | Allow deletion of all notifications |\n\nUse `VERIFY_SSL=false` only for a trusted development instance with a self-signed certificate.\n\n## Available MCP tools\n\nThe API uses predictable `{resource}_{action}` names:\n\n- Tasks: `tasks_list`, `tasks_get`, `tasks_create`, `tasks_update`, `tasks_complete`, `tasks_delete`, `tasks_bulk_update`\n- Projects: `projects_list`, `projects_get`, `projects_create`, `projects_update`, `projects_archive`, `projects_delete`, `projects_duplicate`\n- Labels: `labels_list`, `labels_get`, `labels_create`, `labels_update`, `labels_delete`, `task_labels_add`, `task_labels_remove`, `task_labels_replace`\n- Collaboration: `task_comments_*`, `task_assignees_*`, and `task_relations_*`\n- Advanced: `saved_filters_*`, `notifications_*`, `project_views_*`, and `view_buckets_*`\n- Server: `vikunja_info`\n\nList tools return pagination metadata. Update tools are partial updates, so clients only need to send changed fields. Progress is exposed as `progressPercent` from 0 to 100 and converted to Vikunja's fractional representation.\n\n## Safety\n\nPermanent deletions return an MCP error until their matching `ENABLE_*_DELETE` flag is explicitly set to `true`. Archiving a project and completing a task remain available as safer alternatives. Relation removal and detaching labels or assignees do not delete the related objects themselves.\n\n## Upgrading from 0.1.x\n\nVersion 1.0.0 targets Vikunja API v2 and intentionally removes API v1 compatibility. Tool names are now consistent, including:\n\n| Before | 1.0.0 |\n| --- | --- |\n| `task_get`, `task_create`, `task_update` | `tasks_get`, `tasks_create`, `tasks_update` |\n| `project_get`, `project_create` | `projects_get`, `projects_create` |\n| `comments_*`, `assignees_*`, `relations_*` | `task_comments_*`, `task_assignees_*`, `task_relations_*` |\n| `filter_*`, `views_*`, `buckets_*` | `saved_filters_*`, `project_views_*`, `view_buckets_*` |\n\nUpdate stored prompts or automations that refer to old tool names. Passing a former `/api/v1` URL remains accepted, but requests are sent to `/api/v2`.\n\nVikunja 2.6 does not expose subscription endpoints through its API-token permission registry, so 1.0.0 does not advertise subscription write tools that would fail for the documented API-token setup. Current subscription state remains visible in task and project detail results.\n\n## Development\n\n```bash\nnpm ci\ncp .env.example .env\nnpm run check\nnpm run build\n```\n\nAdditional opt-in checks:\n\n- `npm run test:live` runs a CRUD smoke test against a configured Vikunja instance and removes only records it created.\n- `npm run test:qwen` evaluates tool selection through an OpenAI-compatible endpoint using `LLM_BASE_URL`, `LLM_API_KEY`, and `LLM_MODEL`.\n\nThe sanitized [Vikunja 2.6 API contract](docs/api-spec.json) is included for reproducible endpoint checks.\n\n## Links\n\n- [npm package](https://www.npmjs.com/package/@aimbitgmbh/vikunja-mcp)\n- [GitHub repository](https://github.com/aimbitgmbh/vikunja-mcp)\n- [Issue tracker](https://github.com/aimbitgmbh/vikunja-mcp/issues)\n- [Vikunja](https://vikunja.io/)\n- [Model Context Protocol](https://modelcontextprotocol.io/)\n\nMIT © [aimbit GmbH](https://aimbit.de)\n","readmeFilename":"README.md"}