Skip to content
Back to search

vikunja-mcp

Model Context Protocol server for Vikunja task management. Enables AI assistants to interact with Vikunja instances via MCP.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/democratize-technology--vikunja-mcp/badge.svg)](/listings/democratize-technology--vikunja-mcp)

HTML

<a href="/listings/democratize-technology--vikunja-mcp"><img src="/api/listings/democratize-technology--vikunja-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Option 1: Install from NPM (Recommended)

The easiest way to use vikunja-mcp is through npx in your Claude Desktop or other MCP-compatible client configuration:

{
  "vikunja": {
    "command": "npx",
    "args": ["-y", "@democratize-technology/vikunja-mcp"],
    "env": {
      "VIKUNJA_URL": "https://your-vikunja-instance.com/api/v1",
      "VIKUNJA_API_TOKEN": "your-api-token"
    }
  }
}

Option 2: Local Development

For development or customization:

git clone https://github.com/democratize-technology/vikunja-mcp.git
cd vikunja-mcp
npm install
npm run build

Then configure your MCP client:

{
  "vikunja": {
    "command": "node",
    "args": ["/path/to/vikunja-mcp/dist/index.js"],
    "env": {
      "VIKUNJA_URL": "https://your-vikunja-instance.com/api/v1",
      "VIKUNJA_API_TOKEN": "your-api-token"
    }
  }
}

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,334 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Vikunja MCP Server
  2. A Model Context Protocol (MCP) server that enables AI assistants to interact with Vikunja task management instances.
  3. ## Features
  4. - **Subcommand-based tools** for intuitive AI interactions
  5. - **Session-based authentication** with automatic token management
  6. - **Full task management** operations implemented
  7. - **Complete project management** with CRUD operations
  8. - **Label management** for organizing tasks
  9. - **Team operations** for collaboration (get/update/members limited by API)
  10. - **User management** with settings and search
  11. - **Webhook management** for project automation
  12. - **Batch import** tasks from CSV or JSON files
  13. - **Input validation** for dates, IDs, and hex colors
  14. - **Efficient diff-based updates** for assignees
  15. - **TypeScript with strict mode** for type safety
  16. - **Comprehensive error handling** with typed errors and centralized utilities
  17. - **Production-ready retry logic** with opossum circuit breaker for resilience
  18. - **Enhanced security** with Zod-based input validation and DoS protection
  19. - **Rate limiting protection** against DoS attacks with configurable limits
  20. - **Memory protection** with pagination limits and usage monitoring
  21. - **Simplified architecture** with 90% code reduction for maintainability
  22. ## 🚀 Major Architectural Improvements (v0.2.0)
  23. This release represents a **massive architectural simplification** that eliminates technical debt while enhancing security and reliability:
  24. ### Storage Architecture Refactoring (90% Code Reduction)
  25. - **Before**: 33 files, 9,803 lines of over-engineered storage system
  26. - **After**: 4 files, essential functionality only
  27. - **Eliminated**: Complex orchestrators, health monitors, statistics tracking, migration systems
  28. - **Result**: Same external API with dramatically improved maintainability
  29. ### Zod-Based Filter System (850+ Lines Removed)
  30. - **Before**: Custom tokenizer, parser, and validator with security vulnerabilities
  31. - **After**: Secure Zod schema validation with production-ready parsing
  32. - **Enhanced**: DoS protection, input sanitization, and comprehensive error handling
  33. - **Result**: Faster parsing, better security, and enterprise-grade reliability
  34. ### Production-Ready Retry System (580+ Lines Replaced)
  35. - **Before**: Custom retry logic with maintenance overhead
  36. - **After**: Battle-tested opossum circuit breaker library
  37. - **Features**: Circuit breaker state sharing, automatic recovery, comprehensive monitoring
  38. - **Result**: Production resilience with battle-tested patterns
  39. ### Zero Breaking Changes
  40. All improvements maintain **100% backward compatibility** with existing implementations while providing enhanced reliability and security.
  41. ## Requirements
  42. - Node.js 20+ (LTS versions only)
  43. - Vikunja instance with API access
  44. - API token (starting with `tk_`) or JWT token for authentication
  45. ## Installation
  46. ### Option 1: Install from NPM (Recommended)
  47. The easiest way to use vikunja-mcp is through npx in your Claude Desktop or other MCP-compatible client configuration:
  48. ```json
  49. {
  50. "vikunja": {
  51. "command": "npx",
  52. "args": ["-y", "@democratize-technology/vikunja-mcp"],
  53. "env": {
  54. "VIKUNJA_URL": "https://your-vikunja-instance.com/api/v1",
  55. "VIKUNJA_API_TOKEN": "your-api-token"
  56. }
  57. }
  58. }
  59. ```
  60. ### Option 2: Local Development
  61. For development or customization:
  62. ```bash
  63. git clone https://github.com/democratize-technology/vikunja-mcp.git
  64. cd vikunja-mcp
  65. npm install
  66. npm run build
  67. ```
  68. Then configure your MCP client:
  69. ```json
  70. {
  71. "vikunja": {
  72. "command": "node",
  73. "args": ["/path/to/vikunja-mcp/dist/index.js"],
  74. "env": {
  75. "VIKUNJA_URL": "https://your-vikunja-instance.com/api/v1",
  76. "VIKUNJA_API_TOKEN": "your-api-token"
  77. }
  78. }
  79. }
  80. ```
  81. ## Configuration
  82. ### Logging Configuration
  83. The server includes a structured logging system. Configure it via environment variables:
  84. ```bash
  85. # Enable debug logging (default: false)
  86. DEBUG=true
  87. # Set specific log level (error, warn, info, debug)
  88. # If not set, defaults to 'info' (or 'debug' if DEBUG=true)
  89. LOG_LEVEL=debug
  90. ```
  91. Log output includes timestamps and log levels:
  92. ```
  93. [2025-05-25T17:00:00.000Z] [INFO] Vikunja MCP server started
  94. [2025-05-25T17:00:00.100Z] [DEBUG] Executing tasks tool { subcommand: 'list', args: {...} }
  95. ```
  96. All logs are written to stderr to keep stdout reserved for MCP protocol communication.
  97. ## Authentication Methods
  98. The Vikunja MCP server supports two authentication methods, each with different capabilities:
  99. ### API Token Authentication (Default)
  100. API tokens are the standard authentication method for Vikunja:
  101. - **How to obtain:** Go to Vikunja Settings → API Tokens → Create new token
  102. - **Token format:** Starts with `tk_` (e.g., `tk_abc123def456`)
  103. - **Capabilities:** Full access to tasks, projects, labels, teams, and webhooks
  104. - **Limitations:** Cannot access user-specific endpoints (user profile, settings, export)
  105. - **Best for:** Automation, CI/CD, and general task management
  106. ### JWT Authentication (Advanced)
  107. JWT (JSON Web Token) authentication provides full access to all Vikunja endpoints:
  108. - **How to obtain:** Extract from your browser session (see instructions below)
  109. - **Token format:** Long string starting with `eyJ` (standard JWT format)
  110. - **Capabilities:** Full access to all endpoints including user management and export
  111. - **Limitations:** Tokens expire (typically after 24 hours)
  112. - **Best for:** User management, data export, and operations requiring user context
  113. #### How to Extract Your JWT Token
  114. 1. **Log into Vikunja** in your web browser
  115. 2. **Open Developer Tools** (F12 or right-click → Inspect)
  116. 3. **Go to the Application/Storage tab**
  117. 4. **Find the JWT token:**
  118. - Look in Local Storage → your Vikunja domain
  119. - Find the key named `token` or similar
  120. - The value is your JWT token
  121. 5. **Copy the entire token value** (it's quite long)
  122. #### Using JWT Authentication
  123. ```typescript
  124. // Connect with JWT token - automatically detected!
  125. vikunja_auth.connect({
  126. apiUrl: "https://your-vikunja-instance.com/api/v1",
  127. apiToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  128. })
  129. ```
  130. **Important Notes:**
  131. - JWT tokens expire; you'll need to extract a new one when it expires
  132. - Token type is automatically detected based on format (no flag needed)
  133. - Some tools (users, export) are only available with JWT authentication
  134. ## Quick Start
  135. 1. **Set up authentication (if not using environment variables):**
  136. ```typescript
  137. vikunja_auth.connect({
  138. apiUrl: "https://your-vikunja-instance.com/api/v1",
  139. apiToken: "your-api-token"
  140. })
  141. ```
  142. 2. **Create your first task:**
  143. ```typescript
  144. vikunja_tasks.create({
  145. projectId: 1,
  146. title: "My first task via MCP!"
  147. })
  148. ```
  149. 3. **List all your tasks:**
  150. ```typescript
  151. vikunja_tasks.list({ allProjects: true })
  152. ```
  153. ## Usage
  154. The MCP server exposes tools with subcommands. All operations require authentication first (either via environment variables or manual connection).
  155. ### Authentication
  156. ```typescript
  157. // Connect with API token (automatically detected)
  158. vikunja_auth.connect({
  159. apiUrl: "https://your-vikunja-instance.com/api/v1",
  160. apiToken: "tk_your-api-token"
  161. })
  162. // Connect with JWT token (automatically detected, enables additional tools: users, export)
  163. vikunja_auth.connect({
  164. apiUrl: "https://your-vikunja-instance.com/api/v1",
  165. apiToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  166. })
  167. // Check authentication status
  168. vikunja_auth.status()
  169. // Disconnect and clean up resources
  170. vikunja_auth.disconnect()
  171. ```
  172. ### Task Management Examples
  173. ```typescript
  174. // List all tasks across all projects
  175. vikunja_tasks.list({ allProjects: true })
  176. // List tasks for a specific project with pagination
  177. vikunja_tasks.list({
  178. projectId: 1,
  179. page: 1,
  180. perPage: 20,
  181. sort: "due_date"
  182. })
  183. // List tasks with filters (high priority, not done)
  184. vikunja_tasks.list({
  185. filter: "(priority >= 4 && done = false)"
  186. })
  187. // List tasks with simple filter
  188. vikunja_tasks.list({
  189. filter: "priority >= 3"
  190. })
  191. // List tasks with complex filter conditions
  192. vikunja_tasks.list({
  193. filter: "(priority >= 3 && priority <= 5) || (done = true && updated > '2024-01-01')"
  194. })
  195. // Combine filter with search
  196. vikunja_tasks.list({
  197. filter: "priority >= 4",
  198. search: "urgent"
  199. })
  200. // Create a new task with labels and assignees
  201. vikunja_tasks.create({
  202. projectId: 1,
  203. title: "Complete documentation",
  204. description: "Update README with examples",
  205. dueDate: "2024-12-31T23:59:59Z",
  206. priority: 3,
  207. labels: [1, 2], // Label IDs
  208. assignees: [1, 3] // User IDs
  209. })
  210. // Create a recurring task (repeats every week)
  211. vikunja_tasks.create({
  212. projectId: 1,
  213. title: "Weekly team meeting",
  214. description: "Sync up with the team",
  215. dueDate: "2024-12-01T10:00:00Z",
  216. repeatAfter: 7, // Number of units
  217. repeatMode: "day" // Unit: "day", "week", "month", or "year"
  218. })
  219. // Create a monthly recurring task
  220. vikunja_tasks.create({
  221. projectId: 1,
  222. title: "Monthly report",
  223. repeatAfter: 1,
  224. repeatMode: "month"
  225. })
  226. // Get detailed information about a task
  227. vikunja_tasks.get({ id: 123 })
  228. // Update a task (partial updates supported)
  229. vikunja_tasks.update({
  230. id: 123,
  231. done: true,
  232. priority: 5
  233. })
  234. // Update recurring settings on an existing task
  235. vikunja_tasks.update({
  236. id: 123,
  237. repeatAfter: 14, // Change to bi-weekly
  238. repeatMode: "day"
  239. })
  240. // Update task assignees (uses efficient diff-based approach)
  241. vikunja_tasks.update({
  242. id: 123,
  243. assignees: [1, 2, 4] // Only adds/removes differences
  244. })
  245. // Delete a task
  246. vikunja_tasks.delete({ id: 123 })
  247. // Bulk assign users to a task
  248. vikunja_tasks.assign({
  249. id: 123,
  250. assignees: [2, 3, 4]
  251. })
  252. // Remove users from a task
  253. vikunja_tasks.unassign({
  254. id: 123,
  255. assignees: [2, 4] // Removes only these users
  256. })
  257. // List all assignees for a task
  258. vikunja_tasks.list-assignees({ id: 123 })
  259. // Add a comment to a task
  260. vikunja_tasks.comment({
  261. id: 123,
  262. comment: "This task is now complete!"
  263. })
  264. // List all comments on a task
  265. vikunja_tasks.comment({ id: 123 })
  266. // Create a task relation (e.g., subtask, blocking, related)
  267. vikunja_tasks.relate({
  268. id: 123,
  269. otherTaskId: 124,
  270. relationKind: "subtask" // 124 is a subtask of 123
  271. })
  272. // Available relation kinds:
  273. // - subtask: Other task is a subtask of this task
  274. // - parenttask: Other task is the parent of this task
  275. // - related: Tasks are related
  276. // - duplicateof: This task is a duplicate of the other
  277. // - duplicates: Other task is a duplicate of this one
  278. // - blocking: This task blocks the other
  279. // - blocked: This task is blocked by the other
  280. // - precedes: This task precedes the other
  281. // - follows: This task follows the other
  282. // - copiedfrom: This task was copied from the other
  283. // - copiedto: Other task was copied from this one
  284. // Remove a task relation
  285. vikunja_tasks.unrelate({
  286. id: 123,
  287. otherTaskId: 124,
  288. relationKind: "subtask"
  289. })
  290. // Get all relations for a task
  291. vikunja_tasks.relations({ id: 123 })
  292. // Add a reminder to a task
  293. vikunja_tasks.add-reminder({
  294. id: 123,
  295. reminderDate: "2024-12-25T10:00:00Z"
  296. })
  297. // List all reminders for a task
  298. vikunja_tasks.list-reminders({ id: 123 })
  299. // Remove a specific reminder from a task
  300. vikunja_tasks.remove-reminder({
  301. id: 123,
  302. reminderId: 1
  303. })
  304. // Bulk create multiple tasks at once (max 100)
  305. vikunja_tasks.bulk-create({
  306. projectId: 1,
  307. tasks: [
  308. {
  309. title: "Task 1",
  310. description: "First task",
  311. priority: 3,
  312. labels: [1, 2]
  313. },
  314. {
  315. title: "Task 2",
  316. dueDate: "2024-12-31T23:59:59Z",
  317. assignees: [1]
  318. },
  319. {
  320. title: "Weekly standup",
  321. repeatAfter: 7,
  322. repeatMode: "day"
  323. }
  324. ]
  325. })
  326. // Bulk update multiple tasks with the same field value
  327. vikunja_tasks.bulk-update({
  328. taskIds: [123, 124, 125],
  329. field: "done", // Field to update
  330. value: true // New value for all tasks
  331. })
  332. // Other bulk update examples
  333. vikunja_tasks.bulk-update({
  334. taskIds: [123, 124, 125],
  335. field: "priority",
  336. value: 5
  337. })
  338. vikunja_tasks.bulk-update({
  339. taskIds: [123, 124],
  340. field: "project_id",
  341. value: 2 // Move tasks to different project
  342. })
  343. vikunja_tasks.bulk-update({
  344. taskIds: [123, 124, 125],
  345. field: "labels",
  346. value: [1, 3, 5] // Set same labels on all tasks
  347. })
  348. // Bulk delete multiple tasks (max 100)
  349. vikunja_tasks.bulk-delete({
  350. taskIds: [123, 124, 125]
  351. })
  352. // Batch import tasks from CSV or JSON
  353. vikunja_batch_import({
  354. projectId: 1,
  355. format: "json",
  356. data: JSON.stringify([
  357. {
  358. title: "Task 1",
  359. description: "First imported task",
  360. priority: 3,
  361. dueDate: "2024-12-31T23:59:59Z"
  362. },
  363. {
  364. title: "Task 2",
  365. labels: ["bug", "urgent"], // Will look up label IDs by name
  366. assignees: ["john.doe"] // Will look up user IDs by username
  367. }
  368. ])
  369. })
  370. // Import from CSV with headers
  371. vikunja_batch_import({
  372. projectId: 1,
  373. format: "csv",
  374. data: `title,description,priority,dueDate,labels,assignees
  375. "Task 1","Description with, comma",3,2024-12-31T23:59:59Z,"bug;feature","john.doe"
  376. "Task 2","Another task",5,,"urgent","john.doe;jane.smith"`
  377. })
  378. // Dry run to validate without creating tasks
  379. vikunja_batch_import({
  380. projectId: 1,
  381. format: "json",
  382. data: JSON.stringify([...]),
  383. dryRun: true // Only validates, doesn't create tasks
  384. })
  385. // Continue on errors instead of stopping
  386. vikunja_batch_import({
  387. projectId: 1,
  388. format: "csv",
  389. data: csvData,
  390. skipErrors: true // Skip invalid tasks and continue with valid ones
  391. })
  392. ```
  393. ### Data Export Examples
  394. ```typescript
  395. // Export a project with all its data
  396. vikunja_export_project({
  397. projectId: 1,
  398. includeChildren: false // Only export the specified project
  399. })
  400. // Export a project including all child projects
  401. vikunja_export_project({
  402. projectId: 1,
  403. includeChildren: true // Recursively export child projects
  404. })
  405. // The export returns JSON data with the following structure:
  406. // {
  407. // project: { ... }, // Project details
  408. // tasks: [ ... ], // All tasks in the project
  409. // labels: [ ... ], // All labels used in tasks
  410. // child_projects: [ ... ], // Nested child project exports (if includeChildren: true)
  411. // exported_at: "...", // ISO timestamp of export
  412. // version: "1.0.0" // Export format version
  413. // }
  414. // Request a full user data export (sent via email)
  415. vikunja_request_user_export({
  416. password: "your-password" // Required for security
  417. })
  418. // Download a previously requested user data export
  419. vikunja_download_user_export({
  420. password: "your-password" // Required for security
  421. })
  422. ```
  423. ### Project Management Examples
  424. ```typescript
  425. // List all projects
  426. vikunja_projects.list()
  427. // List projects with search and pagination
  428. vikunja_projects.list({
  429. search: "frontend",
  430. page: 1,
  431. perPage: 10,
  432. isArchived: false
  433. })
  434. // Get a specific project
  435. vikunja_projects.get({ id: 1 })
  436. // Create a new project
  437. vikunja_projects.create({
  438. title: "New Frontend Project",
  439. description: "React-based web application",
  440. hexColor: "#4287f5"
  441. })
  442. // Update a project
  443. vikunja_projects.update({
  444. id: 1,
  445. title: "Updated Project Name",
  446. isArchived: true
  447. })
  448. // Archive a project
  449. vikunja_projects.archive({ id: 1 })
  450. // Unarchive a project
  451. vikunja_projects.unarchive({ id: 1 })
  452. // Delete a project
  453. vikunja_projects.delete({ id: 1 })
  454. // --- Project Hierarchy Management ---
  455. // Create a child project
  456. vikunja_projects.create({
  457. title: "Frontend Module",
  458. description: "React components",
  459. parentProjectId: 1, // Will be a child of project 1
  460. hexColor: "#3498db"
  461. })
  462. // Get all direct children of a project
  463. vikunja_projects.get-children({ id: 1 })
  464. // Returns: Array of projects that have parentProjectId = 1
  465. // Get complete project hierarchy as a tree
  466. vikunja_projects.get-tree({ id: 1 })
  467. // Returns: Project with nested children structure
  468. // {
  469. // id: 1,
  470. // title: "Main Project",
  471. // children: [
  472. // {
  473. // id: 2,
  474. // title: "Frontend Module",
  475. // children: [
  476. // { id: 4, title: "Components", children: [] },
  477. // { id: 5, title: "Styles", children: [] }
  478. // ]
  479. // },
  480. // {
  481. // id: 3,
  482. // title: "Backend Module",
  483. // children: []
  484. // }
  485. // ]
  486. // }
  487. // Get breadcrumb path from root to a project
  488. vikunja_projects.get-breadcrumb({ id: 5 })
  489. // Returns: Array of projects from root to target
  490. // [
  491. // { id: 1, title: "Main Project" },
  492. // { id: 2, title: "Frontend Module" },
  493. // { id: 5, title: "Styles" }
  494. // ]
  495. // Also includes a formatted path: "Main Project > Frontend Module > Styles"
  496. // Move a project to a new parent
  497. vikunja_projects.move({
  498. id: 5, // Project to move
  499. parentProjectId: 3 // New parent
  500. })
  501. // Validates against circular references and depth limits
  502. // Move a project to root level (no parent)
  503. vikunja_projects.move({
  504. id: 5,
  505. parentProjectId: undefined
  506. })
  507. // --- Project Sharing ---
  508. // Create a read-only share link
  509. vikunja_projects.create-share({
  510. id: 1,
  511. right: 0, // 0=Read, 1=Write, 2=Admin
  512. label: "Public read-only access"
  513. })
  514. // Create a password-protected share with write access
  515. vikunja_projects.create-share({
  516. id: 1,
  517. right: 1,
  518. password: "securepassword123",
  519. label: "Team collaboration link"
  520. })
  521. // Create an expiring share link
  522. vikunja_projects.create-share({
  523. id: 1,
  524. right: 0,
  525. expires: "2025-12-31T23:59:59Z",
  526. label: "Temporary access until year end"
  527. })
  528. // List all shares for a project
  529. vikunja_projects.list-shares({ id: 1 })
  530. // Get details of a specific share
  531. vikunja_projects.get-share({
  532. id: 1,
  533. shareId: 123
  534. })
  535. // Delete a share link
  536. vikunja_projects.delete-share({
  537. id: 1,
  538. shareId: 123
  539. })
  540. // Authenticate to access a shared project
  541. vikunja_projects.auth-share({
  542. shareHash: "abc123def456"
  543. })
  544. // Authenticate to a password-protected share
  545. vikunja_projects.auth-share({
  546. shareHash: "abc123def456",
  547. password: "securepassword123"
  548. })
  549. ```
  550. ### Label Management Examples
  551. ```typescript
  552. // List all labels
  553. vikunja_labels.list()
  554. // Search for labels
  555. vikunja_labels.list({
  556. search: "bug",
  557. page: 1,
  558. perPage: 20
  559. })
  560. // Get a specific label
  561. vikunja_labels.get({ id: 1 })
  562. // Create a new label
  563. vikunja_labels.create({
  564. title: "Critical",
  565. description: "Critical priority issues",
  566. hexColor: "#ff0000"
  567. })
  568. // Update a label
  569. vikunja_labels.update({
  570. id: 1,
  571. title: "High Priority",
  572. hexColor: "#ff6600"
  573. })
  574. // Delete a label
  575. vikunja_labels.delete({ id: 1 })
  576. // --- Label Assignment to Tasks ---
  577. // Apply multiple labels to a task
  578. vikunja_tasks.apply-label({
  579. id: 123,
  580. labels: [1, 2, 3] // Apply labels with IDs 1, 2, and 3
  581. })
  582. // Apply a single label
  583. vikunja_tasks.apply-label({
  584. id: 123,
  585. labels: [1] // Apply just the "research" label
  586. })
  587. // Remove specific labels from a task
  588. vikunja_tasks.remove-label({
  589. id: 123,
  590. labels: [2, 3] // Remove labels 2 and 3, keep others
  591. })
  592. // List all labels on a task
  593. vikunja_tasks.list-labels({ id: 123 })
  594. // Returns: Task info with detailed label data including colors and descriptions
  595. ```
  596. ### Team Management Examples
  597. ```typescript
  598. // List all teams
  599. vikunja_teams.list()
  600. // Search for teams
  601. vikunja_teams.list({
  602. search: "frontend",
  603. page: 1,
  604. perPage: 10
  605. })
  606. // Create a new team
  607. vikunja_teams.create({
  608. name: "Frontend Team",
  609. description: "Responsible for UI/UX development"
  610. })
  611. // Delete a team
  612. vikunja_teams.delete({ id: 1 })
  613. // Note: get, update, and members operations are not yet
  614. // implemented in the node-vikunja library
  615. ```
  616. ### User Management Examples
  617. > ⚠️ **Known Issue**: User endpoints may fail with authentication errors even when using valid tokens. This is a known Vikunja API issue. The MCP server will provide helpful error messages when this occurs. If you encounter this issue, please contact your Vikunja server administrator.
  618. ```typescript
  619. // Get current user information
  620. vikunja_users.current()
  621. // Search for users
  622. vikunja_users.search({
  623. search: "john"
  624. })
  625. // Get current user settings
  626. vikunja_users.settings()
  627. // Update user settings
  628. vikunja_users.update-settings({
  629. name: "John Doe",
  630. language: "en",
  631. timezone: "America/New_York",
  632. weekStart: 1 // Monday
  633. })
  634. // Update notification preferences
  635. vikunja_users.update-settings({
  636. emailRemindersEnabled: true, // Enable email reminders for tasks
  637. overdueTasksRemindersEnabled: true, // Enable daily overdue task emails
  638. overdueTasksRemindersTime: "09:00" // Time to send overdue task summary
  639. })
  640. ```
  641. ### Webhook Management Examples
  642. ```typescript
  643. // List all available webhook events
  644. vikunja_webhooks.list-events()
  645. // Returns: ["task.created", "task.updated", "task.deleted", "task.assigned", ...]
  646. // List webhooks for a project
  647. vikunja_webhooks.list({ projectId: 1 })
  648. // Create a webhook for task events
  649. vikunja_webhooks.create({
  650. projectId: 1,
  651. targetUrl: "https://example.com/webhook",
  652. events: ["task.created", "task.updated"],
  653. secret: "my-secret-key" // Optional, for HMAC signing
  654. })
  655. // Create a webhook without secret
  656. vikunja_webhooks.create({
  657. projectId: 1,
  658. targetUrl: "https://example.com/notifications",
  659. events: ["task.assigned", "task.comment.created"]
  660. })
  661. // Get a specific webhook
  662. vikunja_webhooks.get({
  663. projectId: 1,
  664. webhookId: 123
  665. })
  666. // Update webhook events
  667. vikunja_webhooks.update({
  668. projectId: 1,
  669. webhookId: 123,
  670. events: ["task.created", "task.updated", "task.deleted"]
  671. })
  672. // Delete a webhook
  673. vikunja_webhooks.delete({
  674. projectId: 1,
  675. webhookId: 123
  676. })
  677. ```
  678. ### Advanced Filtering Examples
  679. ```typescript
  680. // Create a saved filter for high priority tasks
  681. vikunja_filters.create({
  682. name: "High Priority Tasks",
  683. description: "All undone tasks with priority 4 or 5",
  684. filter: "done = false && priority >= 4",
  685. isGlobal: true
  686. })
  687. // Alternative format using title and filters object
  688. vikunja_filters.create({
  689. title: "🔥 High Priority Tasks",
  690. description: "All tasks with priority 4 or 5 that are not completed",
  691. filters: {
  692. filter_by: ["priority"],
  693. filter_value: ["5"],
  694. filter_comparator: [">="],
  695. filter_concat: ""
  696. },
  697. is_favorite: true
  698. })
  699. // Create a filter with multiple conditions
  700. vikunja_filters.create({
  701. title: "Urgent & Incomplete",
  702. filters: {
  703. filter_by: ["priority", "done"],
  704. filter_value: ["3", "false"],
  705. filter_comparator: [">=", "="],
  706. filter_concat: "&&"
  707. }
  708. })
  709. // Create a project-specific filter
  710. vikunja_filters.create({
  711. name: "This Week's Tasks",
  712. filter: "dueDate >= now && dueDate < now+7d",
  713. projectId: 1,
  714. isGlobal: false
  715. })
  716. // List all saved filters
  717. vikunja_filters.list()
  718. // List filters for a specific project
  719. vikunja_filters.list({ projectId: 1 })
  720. // Apply a saved filter to task listing
  721. vikunja_tasks.list({
  722. filterId: "550e8400-e29b-41d4-a716-446655440000"
  723. })
  724. // Build a filter programmatically
  725. vikunja_filters.build({
  726. conditions: [
  727. { field: "done", operator: "=", value: false },
  728. { field: "priority", operator: ">=", value: 3 },
  729. { field: "assignees", operator: "in", value: ["user1", "user2"] }
  730. ],
  731. groupOperator: "&&"
  732. })
  733. // Returns: { filter: "(done = false && priority >= 3 && assignees in user1, user2)", valid: true }
  734. // Update an existing filter
  735. vikunja_filters.update({
  736. id: "550e8400-e29b-41d4-a716-446655440000",
  737. name: "Critical Tasks",
  738. filter: "done = false && priority = 5"
  739. })
  740. // Validate a filter string
  741. vikunja_filters.validate({
  742. filter: "done = false && priority >= 3"
  743. })
  744. // Returns: { valid: true, errors: [] }
  745. ```
  746. #### Filter Syntax Reference
  747. The Vikunja filter syntax supports SQL-like queries with the following:
  748. **Fields:**
  749. - `done` - Task completion status (boolean)
  750. - `priority` - Task priority (1-5)
  751. - `percentDone` - Completion percentage (0-100)
  752. - `dueDate` - Task due date
  753. - `assignees` - Task assignees
  754. - `labels` - Associated labels
  755. - `created` - Task creation time
  756. - `updated` - Task update time
  757. **Operators:**
  758. - Comparison: `=`, `!=`, `>`, `>=`, `<`, `<=`
  759. - Pattern matching: `like` (uses `%` wildcard)
  760. - List matching: `in`, `not in`
  761. **Date Math:**
  762. - `now` - Current time
  763. - `now+24h` - 24 hours from now
  764. - `now-7d` - 7 days ago
  765. - `now/d` - Start of current day
  766. - Supports: s (seconds), m (minutes), h (hours), d (days), w (weeks), M (months), y (years)
  767. **Examples:**
  768. - `priority = 4`
  769. - `dueDate < now`
  770. - `done = false && priority >= 3`
  771. - `assignees in user1, user2`
  772. - `dueDate >= now && dueDate < now+7d`
  773. - `title like "%urgent%"`
  774. **Smart Hybrid Filtering:** This MCP server implements an intelligent hybrid filtering approach that combines server-side and client-side filtering for optimal performance and reliability:
  775. - **Primary**: Attempts server-side filtering first for maximum performance
  776. - **Fallback**: Falls back to client-side filtering if server-side filtering fails or is unavailable
  777. - **Transparent**: Same filter syntax works regardless of which method is used
  778. - **Optimized**: Includes memory protection with pagination limits to prevent unbounded loading
  779. - **Metadata**: Response includes filtering method used (`serverSideFiltering` or `clientSideFiltering`)
  780. - **Performance**: Server-side filtering significantly reduces network traffic and processing time
  781. ## Response Format
  782. All operations in the Vikunja MCP server follow a standardized response format for consistency and predictability:
  783. ```typescript
  784. interface StandardResponse {
  785. success: boolean;
  786. operation: string; // The operation performed (e.g., 'create', 'update', 'list')
  787. message?: string; // Human-readable description of the result
  788. data?: any; // The primary data returned (task, project, label, etc.)
  789. metadata?: {
  790. timestamp: string; // ISO 8601 timestamp of the operation
  791. [key: string]: any; // Additional operation-specific metadata
  792. };
  793. }
  794. ```
  795. ### Response Examples
  796. **Success:**
  797. ```json
  798. {
  799. "success": true,
  800. "operation": "create",
  801. "message": "Task created successfully",
  802. "data": { "id": 123, "title": "Complete documentation" },
  803. "metadata": { "timestamp": "2025-05-25T12:00:00Z" }
  804. }
  805. ```
  806. **Error:**
  807. ```json
  808. {
  809. "success": false,
  810. "operation": "update",
  811. "message": "Task not found",
  812. "error": { "code": "TASK_NOT_FOUND", "details": "No task exists with ID 999" }
  813. }
  814. ```
  815. This standardized format ensures:
  816. - **Consistency**: All tools return responses in the same structure
  817. - **Predictability**: Clients always know what fields to expect
  818. - **Debugging**: Metadata provides context for troubleshooting
  819. - **Error Handling**: Clear error information with codes and messages
  820. ## Available Tools
  821. ### Authentication
  822. - `vikunja_auth` - Authentication management
  823. - `connect` - Initialize connection with API token
  824. - `status` - Check authentication status
  825. - `refresh` - Refresh authentication token
  826. ### Task Management ✅
  827. - `vikunja_tasks` - Task operations (fully implemented)
  828. - `list` - List tasks with filters
  829. - Filter by project or get all tasks
  830. - Support for pagination, search, sorting
  831. - Filter by completion status
  832. - Apply saved filters with `filterId` parameter
  833. - `create` - Create a new task
  834. - Required: title, projectId
  835. - Optional: description, dueDate, priority, labels, assignees
  836. - Validates date format (ISO 8601) and IDs
  837. - `get` - Get task details by ID
  838. - `update` - Update existing task
  839. - Supports partial updates
  840. - Can update title, description, dueDate, priority, done status
  841. - Can update labels and assignees (uses efficient diff-based approach)
  842. - `delete` - Delete a task by ID
  843. - `assign` - Bulk assign users to tasks
  844. - `unassign` - Remove users from tasks
  845. - `comment` - List or add comments to tasks
  846. - `bulk-update` - Update multiple tasks at once
  847. - Required: taskIds array, field name, value
  848. - Supported fields: done, priority, due_date, project_id, assignees, labels
  849. - Validates field types and values
  850. - ⚠️ Performance: Makes API calls to fetch each updated task
  851. - `bulk-delete` - Delete multiple tasks at once
  852. - Required: taskIds array
  853. - Returns deleted task details for confirmation
  854. - Handles partial failures gracefully
  855. - ⚠️ Performance: Makes individual delete calls for each task
  856. - Recommended: Process in batches of 20 or fewer tasks
  857. - `attach` - Not implemented (file handling not available in MCP)
  858. ### Batch Import ✅
  859. - `vikunja_batch_import` - Import multiple tasks from CSV or JSON (fully implemented)
  860. - Required: projectId, format ('csv' or 'json'), data
  861. - Optional: skipErrors (continue on errors), dryRun (validate only)
  862. - **Batch Size Limit**: Maximum 100 tasks per import
  863. - **CSV Format**:
  864. - Requires header row with field names
  865. - Supports quoted values and escaped quotes
  866. - Fields: title, description, priority, dueDate, labels, assignees
  867. - Labels and assignees as semicolon-separated values (semicolons used to avoid conflicts with CSV commas)
  868. - **JSON Format**:
  869. - Array of task objects
  870. - Same fields as CSV, plus direct support for arrays
  871. - **Features**:
  872. - Automatic label lookup by name
  873. - Automatic user lookup by username
  874. - Validation before creation
  875. - Detailed error reporting
  876. - Dry run mode for testing
  877. - Skip errors option for partial imports
  878. ### Project Management ✅
  879. - `vikunja_projects` - Project operations (fully implemented)
  880. - `list` - List all projects with filters
  881. - Support for pagination and search
  882. - Filter by archived status
  883. - `get` - Get project details by ID
  884. - `create` - Create new project
  885. - Required: title
  886. - Optional: description, parentProjectId, isArchived, hexColor (format: #RRGGBB)
  887. - Validates parent project hierarchy depth (max 10 levels)
  888. - `update` - Update existing project
  889. - Supports partial updates
  890. - Can update all project fields including hexColor (format: #RRGGBB)
  891. - Validates parent project hierarchy depth when changing parent
  892. - `delete` - Delete a project by ID
  893. - `archive` - Archive a project
  894. - `unarchive` - Unarchive a project
  895. - **Hierarchy Management** (New!)
  896. - `get-children` - List direct children of a project
  897. - `get-tree` - Get complete project hierarchy as a tree
  898. - `get-breadcrumb` - Get path from root to a project
  899. - `move` - Move a project to a new parent
  900. - Validates against circular references
  901. - Enforces maximum depth of 10 levels
  902. - **Project Sharing**
  903. - `create-share` - Create share link with permissions
  904. - `list-shares` - List all shares for a project
  905. - `get-share` - Get share details
  906. - `delete-share` - Remove a share link
  907. - `auth-share` - Authenticate to access a shared project
  908. ### Label Management ✅
  909. - `vikunja_labels` - Label operations (fully implemented)
  910. - `list` - List all labels with filters
  911. - Support for pagination and search
  912. - `get` - Get label details by ID
  913. - `create` - Create new label
  914. - Required: title
  915. - Optional: description, hexColor (format: #RRGGBB)
  916. - `update` - Update existing label
  917. - Supports partial updates
  918. - Can update title, description, hexColor
  919. - `delete` - Delete a label by ID
  920. - `apply-label` - Apply one or more labels to a task
  921. - Required: task id, labels array
  922. - Supports bulk label application
  923. - `remove-label` - Remove one or more labels from a task
  924. - Required: task id, labels array
  925. - Supports bulk label removal
  926. - `list-labels` - List all labels assigned to a task
  927. - Required: task id
  928. - Returns detailed label information
  929. ### Project Templates ✅
  930. - `vikunja_templates` - Template operations (fully implemented)
  931. - `create` - Create a template from existing project
  932. - Required: projectId, name
  933. - Optional: description, tags
  934. - Captures all project settings and tasks
  935. - `list` - List all available templates
  936. - Shows template name, tags, and author
  937. - `get` - Get template details by ID
  938. - `update` - Update template metadata
  939. - Can update name, description, tags
  940. - `delete` - Delete a template
  941. - `instantiate` - Create new project from template
  942. - Required: id (template ID), projectName
  943. - Optional: parentProjectId, variables
  944. - Supports variable substitution:
  945. - `{{PROJECT_NAME}}` - The new project name
  946. - `{{TODAY}}` - Current date (YYYY-MM-DD)
  947. - `{{NOW}}` - Current timestamp
  948. - Custom variables via the variables parameter
  949. - Creates all tasks with labels from template
  950. ### Team Management ✅
  951. - `vikunja_teams` - Team operations (partially implemented)
  952. - `list` - List all teams with filters
  953. - Support for pagination and search
  954. - `create` - Create new team
  955. - Required: name
  956. - Optional: description
  957. - `delete` - Delete a team by ID (with fallback API support)
  958. - `get` - Not yet implemented in node-vikunja
  959. - `update` - Not yet implemented in node-vikunja
  960. - `members` - Not yet implemented in node-vikunja
  961. ### User Management ✅
  962. - `vikunja_users` - User operations (fully implemented) **[Requires JWT authentication]**
  963. - `current` - Get current authenticated user info
  964. - `search` - Search for users
  965. - Optional: search query, pagination
  966. - `settings` - Get current user settings
  967. - `update-settings` - Update user settings
  968. - Optional: name, language, timezone, weekStart, frontendSettings
  969. - **Note:** User operations require JWT authentication. When using API token authentication, these tools will not be available.
  970. ### Webhook Management ✅
  971. - `vikunja_webhooks` - Webhook operations for project automation (fully implemented)
  972. - `list-events` - Get all available webhook event types
  973. - `list` - List webhooks for a project
  974. - Required: projectId
  975. - `get` - Get a specific webhook
  976. - Required: projectId, webhookId
  977. - `create` - Create a new webhook
  978. - Required: projectId, targetUrl, events (array)
  979. - Optional: secret (for HMAC signing)
  980. - **Note**: Events are validated against available event types
  981. - `update` - Update webhook events
  982. - Required: projectId, webhookId, events (array)
  983. - **Note**: Events are validated against available event types
  984. - `delete` - Delete a webhook
  985. - Required: projectId, webhookId
  986. **Event Validation**: When creating or updating webhooks, the provided events are automatically validated against the list of available events from the API. Invalid events will result in a clear error message showing which events are invalid and listing all valid options. Valid events are cached for 5 minutes to improve performance.
  987. ### Filter Management ✅
  988. - `vikunja_filters` - Advanced filtering for tasks (fully implemented)
  989. - `list` - List saved filters
  990. - Optional: projectId (for project-specific filters), global flag
  991. - `get` - Get a specific filter by ID
  992. - `create` - Create a new saved filter
  993. - Required: name, filter (query string)
  994. - Optional: description, projectId, isGlobal
  995. - `update` - Update an existing filter
  996. - Required: id
  997. - Optional: name, description, filter, projectId, isGlobal
  998. - `delete` - Delete a saved filter
  999. - `build` - Build a filter string from conditions
  1000. - Required: conditions array
  1001. - Optional: groupOperator (&&, ||)
  1002. - `validate` - Validate a filter string
  1003. **Note:** Saved filters are currently stored in memory and will be lost when the MCP server restarts. For production use, consider implementing persistent storage.
  1004. ### Data Export ✅
  1005. > **⚠️ WARNING: Memory Usage**
  1006. > Export operations load entire project hierarchies into memory. For very large projects with thousands of tasks or deeply nested structures, this may consume significant memory. Consider exporting smaller projects individually.
  1007. - `vikunja_export_project` - Export project data **[Requires JWT authentication]**
  1008. - **Parameters:**
  1009. - `projectId` (required) - ID of the project to export
  1010. - `includeChildren` (optional) - Include child projects recursively (default: false)
  1011. - **Returns:** Complete project data including tasks, labels, and metadata
  1012. - **Features:**
  1013. - Exports all tasks with full details
  1014. - Includes all labels used in the project
  1015. - Optionally includes complete child project hierarchy
  1016. - Circular reference detection for nested projects
  1017. - Export metadata includes timestamp and version
  1018. - **Note:** Export operations require JWT authentication. When using API token authentication, this tool will not be available.
  1019. - `vikunja_request_user_export` - Request full user data export
  1020. - **Parameters:**
  1021. - `password` (required) - User password for security verification
  1022. - **Returns:** Confirmation that export has been requested
  1023. - **Note:** You will receive an email when the export is ready
  1024. - `vikunja_download_user_export` - Download previously requested user data export
  1025. - **Parameters:**
  1026. - `password` (required) - User password for security verification
  1027. - **Returns:** Complete user data export
  1028. - **Note:** Export must be requested first via `vikunja_request_user_export`
  1029. ## Known Limitations
  1030. 1. **File Attachments**: The `attach` subcommand is not implemented due to MCP protocol limitations
  1031. 2. **Team Operations**: Limited functionality due to incomplete node-vikunja API support:
  1032. - Cannot get team by ID
  1033. - Cannot update team information
  1034. - Cannot delete teams
  1035. - Cannot manage team members
  1036. 3. **Pagination**: Some endpoints may not fully support pagination parameters due to API limitations
  1037. 4. **Authentication Issues**: Some Vikunja API endpoints have known authentication issues:
  1038. - **User endpoints**: May fail with token errors even with valid tokens (known Vikunja API limitation)
  1039. - **Bulk operations**: May have authentication issues with certain Vikunja API versions
  1040. - **Label operations**: May fail with authentication errors on some server configurations
  1041. - **Assignee operations**: May fail with authentication errors when creating/updating tasks with assignees
  1042. - The server provides detailed error messages when these issues occur, suggesting workarounds
  1043. ## Security & Performance Features
  1044. ### Security Enhancements
  1045. - **Zod Schema Validation**: Enterprise-grade input validation with comprehensive type checking
  1046. - **DoS Protection**: Input sanitization, length limits, and character allowlisting
  1047. - **Credential Protection**: Automatic masking of sensitive tokens and URLs in logs and error messages
  1048. - **Entity Resolution Service**: Robust label and user mapping with defensive error handling for malformed API responses
  1049. - **Rate Limiting**: Configurable request rate limits and payload size restrictions to prevent DoS attacks
  1050. - **Memory Protection**: Pagination limits and memory usage monitoring to prevent resource exhaustion
  1051. - **Error Handling**: Structured error responses that avoid exposing sensitive system information
  1052. ### Performance Optimizations
  1053. - **Hybrid Filtering**: Smart server-side filtering with client-side fallback for optimal performance
  1054. - **Connection Pooling**: Efficient session management with automatic client caching
  1055. - **Request Batching**: Optimized bulk operations with efficient diff-based updates
  1056. - **Memory Management**: Automatic cleanup and pagination to handle large datasets safely
  1057. - **Thread-Safe Client Management**: Async-only ClientContext API eliminates race conditions in concurrent scenarios
  1058. - **Opossum Circuit Breaker**: Production-ready retry logic with automatic failure detection and recovery
  1059. - **Simplified Storage**: In-memory filter storage with 90% reduced complexity and overhead
  1060. ## Configuration
  1061. ### Environment Variables
  1062. The server supports various configuration options through environment variables:
  1063. #### Basic Configuration
  1064. ```bash
  1065. # Vikunja instance URL (required)
  1066. VIKUNJA_URL=https://your-vikunja-instance.com/api/v1
  1067. # Authentication token (required)
  1068. VIKUNJA_API_TOKEN=your-api-token
  1069. # Enable debug logging (default: false)
  1070. DEBUG=true
  1071. # Set log level (error, warn, info, debug)
  1072. LOG_LEVEL=debug
  1073. ```
  1074. #### Security & Performance Configuration
  1075. ```bash
  1076. # Rate limiting (default: enabled)
  1077. RATE_LIMIT_ENABLED=true
  1078. RATE_LIMIT_PER_MINUTE=60 # Requests per minute (default: 60)
  1079. RATE_LIMIT_PER_HOUR=1000 # Requests per hour (default: 1000)
  1080. # Request size limits (default: 1MB)
  1081. MAX_REQUEST_SIZE=1048576 # Maximum request payload size in bytes
  1082. MAX_RESPONSE_SIZE=10485760 # Maximum response size in bytes (default: 10MB)
  1083. # Execution timeout (default: 30 seconds)
  1084. EXECUTION_TIMEOUT=30000 # Tool execution timeout in milliseconds
  1085. # Memory protection (default: enabled)
  1086. MEMORY_PROTECTION_ENABLED=true
  1087. MAX_TASKS_PER_REQUEST=1000 # Maximum tasks to load per request
  1088. # Circuit breaker configuration (opossum)
  1089. CIRCUIT_BREAKER_ENABLED=true # Enable circuit breaker for API calls
  1090. CIRCUIT_BREAKER_TIMEOUT=60000 # Circuit breaker timeout in milliseconds (default: 60s)
  1091. CIRCUIT_BREAKER_ERRORS_THROTTLE=10 # Errors before opening circuit (default: 10)
  1092. CIRCUIT_BREAKER_RESET_TIMEOUT=30000 # Time to wait before trying half-open state (default: 30s)
  1093. # Filter security (Zod validation)
  1094. FILTER_MAX_LENGTH=1000 # Maximum filter string length (default: 1000)
  1095. FILTER_MAX_VALUE_LENGTH=200 # Maximum individual value length (default: 200)
  1096. ```
  1097. For detailed rate limiting configuration, see [`docs/RATE_LIMITING.md`](docs/RATE_LIMITING.md).
  1098. ## Roadmap
  1099. - [x] ✅ **Security hardening** - Comprehensive vulnerability fixes implemented
  1100. - [x] ✅ **Performance optimization** - Hybrid filtering and memory protection
  1101. - [x] ✅ **Error handling** - Centralized error utilities and structured responses
  1102. - [x] ✅ **Test coverage** - 98.91% function coverage achieved
  1103. - [x] ✅ **Architecture simplification** - 90% code reduction with enhanced maintainability
  1104. - [x] ✅ **Production-ready resilience** - Opossum circuit breaker and Zod validation
  1105. - [ ] Add webhook subscriptions for real-time updates
  1106. - [ ] Add caching for frequently accessed data
  1107. - [ ] Add integration tests with real Vikunja instance
  1108. - [ ] Implement persistent storage for saved filters (optional - in-memory works well)
  1109. ## Contributing
  1110. Please see [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines and workflow.
  1111. ## License
  1112. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.