Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@vikunja-mcp list all tasks in my 'Personal' project"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server that enables AI assistants to interact with Vikunja task management instances.
Subcommand-based tools for intuitive AI interactions
Session-based authentication with automatic token management
Full task management operations implemented
Complete project management with CRUD operations
Label management for organizing tasks
Team operations for collaboration (get/update/members limited by API)
User management with settings and search
Webhook management for project automation
Batch import tasks from CSV or JSON files
Input validation for dates, IDs, and hex colors
Efficient diff-based updates for assignees
TypeScript with strict mode for type safety
Comprehensive error handling with typed errors and centralized utilities
Production-ready retry logic with opossum circuit breaker for resilience
Enhanced security with Zod-based input validation and DoS protection
Rate limiting protection against DoS attacks with configurable limits
Memory protection with pagination limits and usage monitoring
Simplified architecture with 90% code reduction for maintainability
Related MCP server: Vikunja MCP Server
This release represents a massive architectural simplification that eliminates technical debt while enhancing security and reliability:
Before: 33 files, 9,803 lines of over-engineered storage system
After: 4 files, essential functionality only
Eliminated: Complex orchestrators, health monitors, statistics tracking, migration systems
Result: Same external API with dramatically improved maintainability
Before: Custom tokenizer, parser, and validator with security vulnerabilities
After: Secure Zod schema validation with production-ready parsing
Enhanced: DoS protection, input sanitization, and comprehensive error handling
Result: Faster parsing, better security, and enterprise-grade reliability
Before: Custom retry logic with maintenance overhead
After: Battle-tested opossum circuit breaker library
Features: Circuit breaker state sharing, automatic recovery, comprehensive monitoring
Result: Production resilience with battle-tested patterns
All improvements maintain 100% backward compatibility with existing implementations while providing enhanced reliability and security.
Node.js 20+ (LTS versions only)
Vikunja instance with API access
API token (starting with tk_) or JWT token for authentication
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"
}
}
}For development or customization:
git clone https://github.com/democratize-technology/vikunja-mcp.git
cd vikunja-mcp
npm install
npm run buildThen 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"
}
}
}The server includes a structured logging system. Configure it via environment variables:
# Enable debug logging (default: false)
DEBUG=true
# Set specific log level (error, warn, info, debug)
# If not set, defaults to 'info' (or 'debug' if DEBUG=true)
LOG_LEVEL=debugLog output includes timestamps and log levels:
[2025-05-25T17:00:00.000Z] [INFO] Vikunja MCP server started
[2025-05-25T17:00:00.100Z] [DEBUG] Executing tasks tool { subcommand: 'list', args: {...} }All logs are written to stderr to keep stdout reserved for MCP protocol communication.
The Vikunja MCP server supports two authentication methods, each with different capabilities:
API tokens are the standard authentication method for Vikunja:
How to obtain: Go to Vikunja Settings → API Tokens → Create new token
Token format: Starts with tk_ (e.g., tk_abc123def456)
Capabilities: Full access to tasks, projects, labels, teams, and webhooks
Limitations: Cannot access user-specific endpoints (user profile, settings, export)
Best for: Automation, CI/CD, and general task management
JWT (JSON Web Token) authentication provides full access to all Vikunja endpoints:
How to obtain: Extract from your browser session (see instructions below)
Token format: Long string starting with eyJ (standard JWT format)
Capabilities: Full access to all endpoints including user management and export
Limitations: Tokens expire (typically after 24 hours)
Best for: User management, data export, and operations requiring user context
Log into Vikunja in your web browser
Open Developer Tools (F12 or right-click → Inspect)
Go to the Application/Storage tab
Find the JWT token:
Look in Local Storage → your Vikunja domain
Find the key named token or similar
The value is your JWT token
Copy the entire token value (it's quite long)
// Connect with JWT token - automatically detected!
vikunja_auth.connect({
apiUrl: "https://your-vikunja-instance.com/api/v1",
apiToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
})Important Notes:
JWT tokens expire; you'll need to extract a new one when it expires
Token type is automatically detected based on format (no flag needed)
Some tools (users, export) are only available with JWT authentication
Set up authentication (if not using environment variables):
vikunja_auth.connect({
apiUrl: "https://your-vikunja-instance.com/api/v1",
apiToken: "your-api-token"
})Create your first task:
vikunja_tasks.create({
projectId: 1,
title: "My first task via MCP!"
})List all your tasks:
vikunja_tasks.list({ allProjects: true })The MCP server exposes tools with subcommands. All operations require authentication first (either via environment variables or manual connection).
// Connect with API token (automatically detected)
vikunja_auth.connect({
apiUrl: "https://your-vikunja-instance.com/api/v1",
apiToken: "tk_your-api-token"
})
// Connect with JWT token (automatically detected, enables additional tools: users, export)
vikunja_auth.connect({
apiUrl: "https://your-vikunja-instance.com/api/v1",
apiToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
})
// Check authentication status
vikunja_auth.status()
// Disconnect and clean up resources
vikunja_auth.disconnect()// List all tasks across all projects
vikunja_tasks.list({ allProjects: true })
// List tasks for a specific project with pagination
vikunja_tasks.list({
projectId: 1,
page: 1,
perPage: 20,
sort: "due_date"
})
// List tasks with filters (high priority, not done)
vikunja_tasks.list({
filter: "(priority >= 4 && done = false)"
})
// List tasks with simple filter
vikunja_tasks.list({
filter: "priority >= 3"
})
// List tasks with complex filter conditions
vikunja_tasks.list({
filter: "(priority >= 3 && priority <= 5) || (done = true && updated > '2024-01-01')"
})
// Combine filter with search
vikunja_tasks.list({
filter: "priority >= 4",
search: "urgent"
})
// Create a new task with labels and assignees
vikunja_tasks.create({
projectId: 1,
title: "Complete documentation",
description: "Update README with examples",
dueDate: "2024-12-31T23:59:59Z",
priority: 3,
labels: [1, 2], // Label IDs
assignees: [1, 3] // User IDs
})
// Create a recurring task (repeats every week)
vikunja_tasks.create({
projectId: 1,
title: "Weekly team meeting",
description: "Sync up with the team",
dueDate: "2024-12-01T10:00:00Z",
repeatAfter: 7, // Number of units
repeatMode: "day" // Unit: "day", "week", "month", or "year"
})
// Create a monthly recurring task
vikunja_tasks.create({
projectId: 1,
title: "Monthly report",
repeatAfter: 1,
repeatMode: "month"
})
// Get detailed information about a task
vikunja_tasks.get({ id: 123 })
// Update a task (partial updates supported)
vikunja_tasks.update({
id: 123,
done: true,
priority: 5
})
// Update recurring settings on an existing task
vikunja_tasks.update({
id: 123,
repeatAfter: 14, // Change to bi-weekly
repeatMode: "day"
})
// Update task assignees (uses efficient diff-based approach)
vikunja_tasks.update({
id: 123,
assignees: [1, 2, 4] // Only adds/removes differences
})
// Delete a task
vikunja_tasks.delete({ id: 123 })
// Bulk assign users to a task
vikunja_tasks.assign({
id: 123,
assignees: [2, 3, 4]
})
// Remove users from a task
vikunja_tasks.unassign({
id: 123,
assignees: [2, 4] // Removes only these users
})
// List all assignees for a task
vikunja_tasks.list-assignees({ id: 123 })
// Add a comment to a task
vikunja_tasks.comment({
id: 123,
comment: "This task is now complete!"
})
// List all comments on a task
vikunja_tasks.comment({ id: 123 })
// Create a task relation (e.g., subtask, blocking, related)
vikunja_tasks.relate({
id: 123,
otherTaskId: 124,
relationKind: "subtask" // 124 is a subtask of 123
})
// Available relation kinds:
// - subtask: Other task is a subtask of this task
// - parenttask: Other task is the parent of this task
// - related: Tasks are related
// - duplicateof: This task is a duplicate of the other
// - duplicates: Other task is a duplicate of this one
// - blocking: This task blocks the other
// - blocked: This task is blocked by the other
// - precedes: This task precedes the other
// - follows: This task follows the other
// - copiedfrom: This task was copied from the other
// - copiedto: Other task was copied from this one
// Remove a task relation
vikunja_tasks.unrelate({
id: 123,
otherTaskId: 124,
relationKind: "subtask"
})
// Get all relations for a task
vikunja_tasks.relations({ id: 123 })
// Add a reminder to a task
vikunja_tasks.add-reminder({
id: 123,
reminderDate: "2024-12-25T10:00:00Z"
})
// List all reminders for a task
vikunja_tasks.list-reminders({ id: 123 })
// Remove a specific reminder from a task
vikunja_tasks.remove-reminder({
id: 123,
reminderId: 1
})
// Bulk create multiple tasks at once (max 100)
vikunja_tasks.bulk-create({
projectId: 1,
tasks: [
{
title: "Task 1",
description: "First task",
priority: 3,
labels: [1, 2]
},
{
title: "Task 2",
dueDate: "2024-12-31T23:59:59Z",
assignees: [1]
},
{
title: "Weekly standup",
repeatAfter: 7,
repeatMode: "day"
}
]
})
// Bulk update multiple tasks with the same field value
vikunja_tasks.bulk-update({
taskIds: [123, 124, 125],
field: "done", // Field to update
value: true // New value for all tasks
})
// Other bulk update examples
vikunja_tasks.bulk-update({
taskIds: [123, 124, 125],
field: "priority",
value: 5
})
vikunja_tasks.bulk-update({
taskIds: [123, 124],
field: "project_id",
value: 2 // Move tasks to different project
})
vikunja_tasks.bulk-update({
taskIds: [123, 124, 125],
field: "labels",
value: [1, 3, 5] // Set same labels on all tasks
})
// Bulk delete multiple tasks (max 100)
vikunja_tasks.bulk-delete({
taskIds: [123, 124, 125]
})
// Batch import tasks from CSV or JSON
vikunja_batch_import({
projectId: 1,
format: "json",
data: JSON.stringify([
{
title: "Task 1",
description: "First imported task",
priority: 3,
dueDate: "2024-12-31T23:59:59Z"
},
{
title: "Task 2",
labels: ["bug", "urgent"], // Will look up label IDs by name
assignees: ["john.doe"] // Will look up user IDs by username
}
])
})
// Import from CSV with headers
vikunja_batch_import({
projectId: 1,
format: "csv",
data: `title,description,priority,dueDate,labels,assignees
"Task 1","Description with, comma",3,2024-12-31T23:59:59Z,"bug;feature","john.doe"
"Task 2","Another task",5,,"urgent","john.doe;jane.smith"`
})
// Dry run to validate without creating tasks
vikunja_batch_import({
projectId: 1,
format: "json",
data: JSON.stringify([...]),
dryRun: true // Only validates, doesn't create tasks
})
// Continue on errors instead of stopping
vikunja_batch_import({
projectId: 1,
format: "csv",
data: csvData,
skipErrors: true // Skip invalid tasks and continue with valid ones
})// Export a project with all its data
vikunja_export_project({
projectId: 1,
includeChildren: false // Only export the specified project
})
// Export a project including all child projects
vikunja_export_project({
projectId: 1,
includeChildren: true // Recursively export child projects
})
// The export returns JSON data with the following structure:
// {
// project: { ... }, // Project details
// tasks: [ ... ], // All tasks in the project
// labels: [ ... ], // All labels used in tasks
// child_projects: [ ... ], // Nested child project exports (if includeChildren: true)
// exported_at: "...", // ISO timestamp of export
// version: "1.0.0" // Export format version
// }
// Request a full user data export (sent via email)
vikunja_request_user_export({
password: "your-password" // Required for security
})
// Download a previously requested user data export
vikunja_download_user_export({
password: "your-password" // Required for security
})// List all projects
vikunja_projects.list()
// List projects with search and pagination
vikunja_projects.list({
search: "frontend",
page: 1,
perPage: 10,
isArchived: false
})
// Get a specific project
vikunja_projects.get({ id: 1 })
// Create a new project
vikunja_projects.create({
title: "New Frontend Project",
description: "React-based web application",
hexColor: "#4287f5"
})
// Update a project
vikunja_projects.update({
id: 1,
title: "Updated Project Name",
isArchived: true
})
// Archive a project
vikunja_projects.archive({ id: 1 })
// Unarchive a project
vikunja_projects.unarchive({ id: 1 })
// Delete a project
vikunja_projects.delete({ id: 1 })
// --- Project Hierarchy Management ---
// Create a child project
vikunja_projects.create({
title: "Frontend Module",
description: "React components",
parentProjectId: 1, // Will be a child of project 1
hexColor: "#3498db"
})
// Get all direct children of a project
vikunja_projects.get-children({ id: 1 })
// Returns: Array of projects that have parentProjectId = 1
// Get complete project hierarchy as a tree
vikunja_projects.get-tree({ id: 1 })
// Returns: Project with nested children structure
// {
// id: 1,
// title: "Main Project",
// children: [
// {
// id: 2,
// title: "Frontend Module",
// children: [
// { id: 4, title: "Components", children: [] },
// { id: 5, title: "Styles", children: [] }
// ]
// },
// {
// id: 3,
// title: "Backend Module",
// children: []
// }
// ]
// }
// Get breadcrumb path from root to a project
vikunja_projects.get-breadcrumb({ id: 5 })
// Returns: Array of projects from root to target
// [
// { id: 1, title: "Main Project" },
// { id: 2, title: "Frontend Module" },
// { id: 5, title: "Styles" }
// ]
// Also includes a formatted path: "Main Project > Frontend Module > Styles"
// Move a project to a new parent
vikunja_projects.move({
id: 5, // Project to move
parentProjectId: 3 // New parent
})
// Validates against circular references and depth limits
// Move a project to root level (no parent)
vikunja_projects.move({
id: 5,
parentProjectId: undefined
})
// --- Project Sharing ---
// Create a read-only share link
vikunja_projects.create-share({
id: 1,
right: 0, // 0=Read, 1=Write, 2=Admin
label: "Public read-only access"
})
// Create a password-protected share with write access
vikunja_projects.create-share({
id: 1,
right: 1,
password: "securepassword123",
label: "Team collaboration link"
})
// Create an expiring share link
vikunja_projects.create-share({
id: 1,
right: 0,
expires: "2025-12-31T23:59:59Z",
label: "Temporary access until year end"
})
// List all shares for a project
vikunja_projects.list-shares({ id: 1 })
// Get details of a specific share
vikunja_projects.get-share({
id: 1,
shareId: 123
})
// Delete a share link
vikunja_projects.delete-share({
id: 1,
shareId: 123
})
// Authenticate to access a shared project
vikunja_projects.auth-share({
shareHash: "abc123def456"
})
// Authenticate to a password-protected share
vikunja_projects.auth-share({
shareHash: "abc123def456",
password: "securepassword123"
})// List all labels
vikunja_labels.list()
// Search for labels
vikunja_labels.list({
search: "bug",
page: 1,
perPage: 20
})
// Get a specific label
vikunja_labels.get({ id: 1 })
// Create a new label
vikunja_labels.create({
title: "Critical",
description: "Critical priority issues",
hexColor: "#ff0000"
})
// Update a label
vikunja_labels.update({
id: 1,
title: "High Priority",
hexColor: "#ff6600"
})
// Delete a label
vikunja_labels.delete({ id: 1 })
// --- Label Assignment to Tasks ---
// Apply multiple labels to a task
vikunja_tasks.apply-label({
id: 123,
labels: [1, 2, 3] // Apply labels with IDs 1, 2, and 3
})
// Apply a single label
vikunja_tasks.apply-label({
id: 123,
labels: [1] // Apply just the "research" label
})
// Remove specific labels from a task
vikunja_tasks.remove-label({
id: 123,
labels: [2, 3] // Remove labels 2 and 3, keep others
})
// List all labels on a task
vikunja_tasks.list-labels({ id: 123 })
// Returns: Task info with detailed label data including colors and descriptions// List all teams
vikunja_teams.list()
// Search for teams
vikunja_teams.list({
search: "frontend",
page: 1,
perPage: 10
})
// Create a new team
vikunja_teams.create({
name: "Frontend Team",
description: "Responsible for UI/UX development"
})
// Delete a team
vikunja_teams.delete({ id: 1 })
// Note: get, update, and members operations are not yet
// implemented in the node-vikunja library⚠️ 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.
// Get current user information
vikunja_users.current()
// Search for users
vikunja_users.search({
search: "john"
})
// Get current user settings
vikunja_users.settings()
// Update user settings
vikunja_users.update-settings({
name: "John Doe",
language: "en",
timezone: "America/New_York",
weekStart: 1 // Monday
})
// Update notification preferences
vikunja_users.update-settings({
emailRemindersEnabled: true, // Enable email reminders for tasks
overdueTasksRemindersEnabled: true, // Enable daily overdue task emails
overdueTasksRemindersTime: "09:00" // Time to send overdue task summary
})// List all available webhook events
vikunja_webhooks.list-events()
// Returns: ["task.created", "task.updated", "task.deleted", "task.assigned", ...]
// List webhooks for a project
vikunja_webhooks.list({ projectId: 1 })
// Create a webhook for task events
vikunja_webhooks.create({
projectId: 1,
targetUrl: "https://example.com/webhook",
events: ["task.created", "task.updated"],
secret: "my-secret-key" // Optional, for HMAC signing
})
// Create a webhook without secret
vikunja_webhooks.create({
projectId: 1,
targetUrl: "https://example.com/notifications",
events: ["task.assigned", "task.comment.created"]
})
// Get a specific webhook
vikunja_webhooks.get({
projectId: 1,
webhookId: 123
})
// Update webhook events
vikunja_webhooks.update({
projectId: 1,
webhookId: 123,
events: ["task.created", "task.updated", "task.deleted"]
})
// Delete a webhook
vikunja_webhooks.delete({
projectId: 1,
webhookId: 123
})// Create a saved filter for high priority tasks
vikunja_filters.create({
name: "High Priority Tasks",
description: "All undone tasks with priority 4 or 5",
filter: "done = false && priority >= 4",
isGlobal: true
})
// Alternative format using title and filters object
vikunja_filters.create({
title: "🔥 High Priority Tasks",
description: "All tasks with priority 4 or 5 that are not completed",
filters: {
filter_by: ["priority"],
filter_value: ["5"],
filter_comparator: [">="],
filter_concat: ""
},
is_favorite: true
})
// Create a filter with multiple conditions
vikunja_filters.create({
title: "Urgent & Incomplete",
filters: {
filter_by: ["priority", "done"],
filter_value: ["3", "false"],
filter_comparator: [">=", "="],
filter_concat: "&&"
}
})
// Create a project-specific filter
vikunja_filters.create({
name: "This Week's Tasks",
filter: "dueDate >= now && dueDate < now+7d",
projectId: 1,
isGlobal: false
})
// List all saved filters
vikunja_filters.list()
// List filters for a specific project
vikunja_filters.list({ projectId: 1 })
// Apply a saved filter to task listing
vikunja_tasks.list({
filterId: "550e8400-e29b-41d4-a716-446655440000"
})
// Build a filter programmatically
vikunja_filters.build({
conditions: [
{ field: "done", operator: "=", value: false },
{ field: "priority", operator: ">=", value: 3 },
{ field: "assignees", operator: "in", value: ["user1", "user2"] }
],
groupOperator: "&&"
})
// Returns: { filter: "(done = false && priority >= 3 && assignees in user1, user2)", valid: true }
// Update an existing filter
vikunja_filters.update({
id: "550e8400-e29b-41d4-a716-446655440000",
name: "Critical Tasks",
filter: "done = false && priority = 5"
})
// Validate a filter string
vikunja_filters.validate({
filter: "done = false && priority >= 3"
})
// Returns: { valid: true, errors: [] }The Vikunja filter syntax supports SQL-like queries with the following:
Fields:
done - Task completion status (boolean)
priority - Task priority (1-5)
percentDone - Completion percentage (0-100)
dueDate - Task due date
assignees - Task assignees
labels - Associated labels
created - Task creation time
updated - Task update time
Operators:
Comparison: =, !=, >, >=, <, <=
Pattern matching: like (uses % wildcard)
List matching: in, not in
Date Math:
now - Current time
now+24h - 24 hours from now
now-7d - 7 days ago
now/d - Start of current day
Supports: s (seconds), m (minutes), h (hours), d (days), w (weeks), M (months), y (years)
Examples:
priority = 4
dueDate < now
done = false && priority >= 3
assignees in user1, user2
dueDate >= now && dueDate < now+7d
title like "%urgent%"
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:
Primary: Attempts server-side filtering first for maximum performance
Fallback: Falls back to client-side filtering if server-side filtering fails or is unavailable
Transparent: Same filter syntax works regardless of which method is used
Optimized: Includes memory protection with pagination limits to prevent unbounded loading
Metadata: Response includes filtering method used (serverSideFiltering or clientSideFiltering)
Performance: Server-side filtering significantly reduces network traffic and processing time
All operations in the Vikunja MCP server follow a standardized response format for consistency and predictability:
interface StandardResponse {
success: boolean;
operation: string; // The operation performed (e.g., 'create', 'update', 'list')
message?: string; // Human-readable description of the result
data?: any; // The primary data returned (task, project, label, etc.)
metadata?: {
timestamp: string; // ISO 8601 timestamp of the operation
[key: string]: any; // Additional operation-specific metadata
};
}Success:
{
"success": true,
"operation": "create",
"message": "Task created successfully",
"data": { "id": 123, "title": "Complete documentation" },
"metadata": { "timestamp": "2025-05-25T12:00:00Z" }
}Error:
{
"success": false,
"operation": "update",
"message": "Task not found",
"error": { "code": "TASK_NOT_FOUND", "details": "No task exists with ID 999" }
}This standardized format ensures:
Consistency: All tools return responses in the same structure
Predictability: Clients always know what fields to expect
Debugging: Metadata provides context for troubleshooting
Error Handling: Clear error information with codes and messages
vikunja_auth - Authentication management
connect - Initialize connection with API token
status - Check authentication status
refresh - Refresh authentication token
vikunja_tasks - Task operations (fully implemented)
list - List tasks with filters
Filter by project or get all tasks
Support for pagination, search, sorting
Filter by completion status
Apply saved filters with filterId parameter
create - Create a new task
Required: title, projectId
Optional: description, dueDate, priority, labels, assignees
Validates date format (ISO 8601) and IDs
get - Get task details by ID
update - Update existing task
Supports partial updates
Can update title, description, dueDate, priority, done status
Can update labels and assignees (uses efficient diff-based approach)
delete - Delete a task by ID
assign - Bulk assign users to tasks
unassign - Remove users from tasks
comment - List or add comments to tasks
bulk-update - Update multiple tasks at once
Required: taskIds array, field name, value
Supported fields: done, priority, due_date, project_id, assignees, labels
Validates field types and values
⚠️ Performance: Makes API calls to fetch each updated task
bulk-delete - Delete multiple tasks at once
Required: taskIds array
Returns deleted task details for confirmation
Handles partial failures gracefully
⚠️ Performance: Makes individual delete calls for each task
Recommended: Process in batches of 20 or fewer tasks
attach - Not implemented (file handling not available in MCP)
vikunja_batch_import - Import multiple tasks from CSV or JSON (fully implemented)
Required: projectId, format ('csv' or 'json'), data
Optional: skipErrors (continue on errors), dryRun (validate only)
Batch Size Limit: Maximum 100 tasks per import
CSV Format:
Requires header row with field names
Supports quoted values and escaped quotes
Fields: title, description, priority, dueDate, labels, assignees
Labels and assignees as semicolon-separated values (semicolons used to avoid conflicts with CSV commas)
JSON Format:
Array of task objects
Same fields as CSV, plus direct support for arrays
Features:
Automatic label lookup by name
Automatic user lookup by username
Validation before creation
Detailed error reporting
Dry run mode for testing
Skip errors option for partial imports
vikunja_projects - Project operations (fully implemented)
list - List all projects with filters
Support for pagination and search
Filter by archived status
get - Get project details by ID
create - Create new project
Required: title
Optional: description, parentProjectId, isArchived, hexColor (format: #RRGGBB)
Validates parent project hierarchy depth (max 10 levels)
update - Update existing project
Supports partial updates
Can update all project fields including hexColor (format: #RRGGBB)
Validates parent project hierarchy depth when changing parent
delete - Delete a project by ID
archive - Archive a project
unarchive - Unarchive a project
Hierarchy Management (New!)
get-children - List direct children of a project
get-tree - Get complete project hierarchy as a tree
get-breadcrumb - Get path from root to a project
move - Move a project to a new parent
Validates against circular references
Enforces maximum depth of 10 levels
Project Sharing
create-share - Create share link with permissions
list-shares - List all shares for a project
get-share - Get share details
delete-share - Remove a share link
auth-share - Authenticate to access a shared project
vikunja_labels - Label operations (fully implemented)
list - List all labels with filters
Support for pagination and search
get - Get label details by ID
create - Create new label
Required: title
Optional: description, hexColor (format: #RRGGBB)
update - Update existing label
Supports partial updates
Can update title, description, hexColor
delete - Delete a label by ID
apply-label - Apply one or more labels to a task
Required: task id, labels array
Supports bulk label application
remove-label - Remove one or more labels from a task
Required: task id, labels array
Supports bulk label removal
list-labels - List all labels assigned to a task
Required: task id
Returns detailed label information
vikunja_templates - Template operations (fully implemented)
create - Create a template from existing project
Required: projectId, name
Optional: description, tags
Captures all project settings and tasks
list - List all available templates
Shows template name, tags, and author
get - Get template details by ID
update - Update template metadata
Can update name, description, tags
delete - Delete a template
instantiate - Create new project from template
Required: id (template ID), projectName
Optional: parentProjectId, variables
Supports variable substitution:
{{PROJECT_NAME}} - The new project name
{{TODAY}} - Current date (YYYY-MM-DD)
{{NOW}} - Current timestamp
Custom variables via the variables parameter
Creates all tasks with labels from template
vikunja_teams - Team operations (partially implemented)
list - List all teams with filters
Support for pagination and search
create - Create new team
Required: name
Optional: description
delete - Delete a team by ID (with fallback API support)
get - Not yet implemented in node-vikunja
update - Not yet implemented in node-vikunja
members - Not yet implemented in node-vikunja
vikunja_users - User operations (fully implemented) [Requires JWT authentication]
current - Get current authenticated user info
search - Search for users
Optional: search query, pagination
settings - Get current user settings
update-settings - Update user settings
Optional: name, language, timezone, weekStart, frontendSettings
Note: User operations require JWT authentication. When using API token authentication, these tools will not be available.
vikunja_webhooks - Webhook operations for project automation (fully implemented)
list-events - Get all available webhook event types
list - List webhooks for a project
Required: projectId
get - Get a specific webhook
Required: projectId, webhookId
create - Create a new webhook
Required: projectId, targetUrl, events (array)
Optional: secret (for HMAC signing)
Note: Events are validated against available event types
update - Update webhook events
Required: projectId, webhookId, events (array)
Note: Events are validated against available event types
delete - Delete a webhook
Required: projectId, webhookId
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.
vikunja_filters - Advanced filtering for tasks (fully implemented)
list - List saved filters
Optional: projectId (for project-specific filters), global flag
get - Get a specific filter by ID
create - Create a new saved filter
Required: name, filter (query string)
Optional: description, projectId, isGlobal
update - Update an existing filter
Required: id
Optional: name, description, filter, projectId, isGlobal
delete - Delete a saved filter
build - Build a filter string from conditions
Required: conditions array
Optional: groupOperator (&&, ||)
validate - Validate a filter string
Note: Saved filters are currently stored in memory and will be lost when the MCP server restarts. For production use, consider implementing persistent storage.
⚠️ WARNING: Memory Usage
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.
vikunja_export_project - Export project data [Requires JWT authentication]
Parameters:
projectId (required) - ID of the project to export
includeChildren (optional) - Include child projects recursively (default: false)
Returns: Complete project data including tasks, labels, and metadata
Features:
Exports all tasks with full details
Includes all labels used in the project
Optionally includes complete child project hierarchy
Circular reference detection for nested projects
Export metadata includes timestamp and version
Note: Export operations require JWT authentication. When using API token authentication, this tool will not be available.
vikunja_request_user_export - Request full user data export
Parameters:
password (required) - User password for security verification
Returns: Confirmation that export has been requested
Note: You will receive an email when the export is ready
vikunja_download_user_export - Download previously requested user data export
Parameters:
password (required) - User password for security verification
Returns: Complete user data export
Note: Export must be requested first via vikunja_request_user_export
File Attachments: The attach subcommand is not implemented due to MCP protocol limitations
Team Operations: Limited functionality due to incomplete node-vikunja API support:
Cannot get team by ID
Cannot update team information
Cannot delete teams
Cannot manage team members
Pagination: Some endpoints may not fully support pagination parameters due to API limitations
Authentication Issues: Some Vikunja API endpoints have known authentication issues:
User endpoints: May fail with token errors even with valid tokens (known Vikunja API limitation)
Bulk operations: May have authentication issues with certain Vikunja API versions
Label operations: May fail with authentication errors on some server configurations
Assignee operations: May fail with authentication errors when creating/updating tasks with assignees
The server provides detailed error messages when these issues occur, suggesting workarounds
Zod Schema Validation: Enterprise-grade input validation with comprehensive type checking
DoS Protection: Input sanitization, length limits, and character allowlisting
Credential Protection: Automatic masking of sensitive tokens and URLs in logs and error messages
Entity Resolution Service: Robust label and user mapping with defensive error handling for malformed API responses
Rate Limiting: Configurable request rate limits and payload size restrictions to prevent DoS attacks
Memory Protection: Pagination limits and memory usage monitoring to prevent resource exhaustion
Error Handling: Structured error responses that avoid exposing sensitive system information
Hybrid Filtering: Smart server-side filtering with client-side fallback for optimal performance
Connection Pooling: Efficient session management with automatic client caching
Request Batching: Optimized bulk operations with efficient diff-based updates
Memory Management: Automatic cleanup and pagination to handle large datasets safely
Thread-Safe Client Management: Async-only ClientContext API eliminates race conditions in concurrent scenarios
Opossum Circuit Breaker: Production-ready retry logic with automatic failure detection and recovery
Simplified Storage: In-memory filter storage with 90% reduced complexity and overhead
The server supports various configuration options through environment variables:
# Vikunja instance URL (required)
VIKUNJA_URL=https://your-vikunja-instance.com/api/v1
# Authentication token (required)
VIKUNJA_API_TOKEN=your-api-token
# Enable debug logging (default: false)
DEBUG=true
# Set log level (error, warn, info, debug)
LOG_LEVEL=debug# Rate limiting (default: enabled)
RATE_LIMIT_ENABLED=true
RATE_LIMIT_PER_MINUTE=60 # Requests per minute (default: 60)
RATE_LIMIT_PER_HOUR=1000 # Requests per hour (default: 1000)
# Request size limits (default: 1MB)
MAX_REQUEST_SIZE=1048576 # Maximum request payload size in bytes
MAX_RESPONSE_SIZE=10485760 # Maximum response size in bytes (default: 10MB)
# Execution timeout (default: 30 seconds)
EXECUTION_TIMEOUT=30000 # Tool execution timeout in milliseconds
# Memory protection (default: enabled)
MEMORY_PROTECTION_ENABLED=true
MAX_TASKS_PER_REQUEST=1000 # Maximum tasks to load per request
# Circuit breaker configuration (opossum)
CIRCUIT_BREAKER_ENABLED=true # Enable circuit breaker for API calls
CIRCUIT_BREAKER_TIMEOUT=60000 # Circuit breaker timeout in milliseconds (default: 60s)
CIRCUIT_BREAKER_ERRORS_THROTTLE=10 # Errors before opening circuit (default: 10)
CIRCUIT_BREAKER_RESET_TIMEOUT=30000 # Time to wait before trying half-open state (default: 30s)
# Filter security (Zod validation)
FILTER_MAX_LENGTH=1000 # Maximum filter string length (default: 1000)
FILTER_MAX_VALUE_LENGTH=200 # Maximum individual value length (default: 200)For detailed rate limiting configuration, see docs/RATE_LIMITING.md.
✅ Security hardening - Comprehensive vulnerability fixes implemented
✅ Performance optimization - Hybrid filtering and memory protection
✅ Error handling - Centralized error utilities and structured responses
✅ Test coverage - 98.91% function coverage achieved
✅ Architecture simplification - 90% code reduction with enhanced maintainability
✅ Production-ready resilience - Opossum circuit breaker and Zod validation
Add webhook subscriptions for real-time updates
Add caching for frequently accessed data
Add integration tests with real Vikunja instance
Implement persistent storage for saved filters (optional - in-memory works well)
Please see CONTRIBUTING.md for development guidelines and workflow.
MIT
Manage authentication with Vikunja API (connect, status, refresh, disconnect)
| Name | Required | Description | Default |
|---|---|---|---|
| apiUrl | No | ||
| apiToken | No | ||
| subcommand | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits, but it only gives a vague verb 'Manage'. It doesn't state that connect and disconnect change state, or that status is read-only, or what happens on error.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The single sentence is concise and front-loaded, immediately conveying the tool's purpose and scope. Every part is necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and the description lacks details about return values, parameter constraints, or subcommand behavior. Given its complexity (3 params, 4 subcommands), the description is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no descriptions (0% coverage), and the description does not explain the parameters apiUrl or apiToken. It only lists the subcommand, which is already in the schema as an enum.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it manages authentication and lists the subcommands (connect, status, refresh, disconnect). This differentiates it from sibling tools that deal with other entities like projects or tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing to connect first) or when to switch between subcommands.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Import tasks in bulk from CSV or JSON formats with error handling and dry-run support
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | ||
| dryRun | No | ||
| format | Yes | ||
| projectId | Yes | ||
| skipErrors | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It mentions error handling and dry-run, which are useful behavioral traits. However, it does not disclose whether the tool is destructive (mutates state), permission requirements, or behavior on duplicate imports. Bare minimum but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that front-loads the action and key features. No wasted words; every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters (3 required), no output schema, and no annotations, the description is too brief. It lacks details on data formatting, error behavior, limits, and return values. An import tool requires more complete guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should add meaning to parameters. It only hints at 'format' (CSV/JSON) and 'dryRun' (dry-run support). Other parameters like 'data', 'projectId', and 'skipErrors' are not explained, leaving the agent to infer from names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: importing tasks in bulk from CSV or JSON. It also mentions error handling and dry-run support, making the purpose distinct from sibling tools like vikunja_task_bulk which may handle other bulk operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide guidance on when to use this tool versus alternatives. No exclusions or context is given; it simply states what the tool does without recommending scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Kanban buckets (columns/statuses): list a project's views, list a view's buckets, and MOVE a task into a bucket. Use this to move a task between kanban columns, e.g. Backlog -> Review -> Done.
| Name | Required | Description | Default |
|---|---|---|---|
| taskId | No | ||
| viewId | No | ||
| bucketId | No | ||
| position | No | ||
| operation | Yes | ||
| projectId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It describes three operations (list-views, list-buckets, move-task) and implies write operations for move-task, but it does not mention permissions, side effects, error conditions, or the effect on task state beyond moving.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences that front-load the core capabilities and provide a helpful example. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (three operations, 6 parameters, no output schema or annotations), the description covers the basics but lacks details like required parameters for each operation, ordering of list operations to get IDs, and error handling. It is adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% parameter description coverage, so the description should compensate. It mentions the operations and projectId implicitly, but does not explain the meaning or requirements of viewId, bucketId, taskId, or position. The agent has to infer parameter roles from the operation names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: list a project's views, list a view's buckets, and move a task into a bucket. It uses specific verbs and resource (buckets) and provides an example ('Backlog -> Review -> Done'), differentiating it from sibling tools that handle tasks, labels, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a clear usage directive: 'Use this to move a task between kanban columns.' This gives context for when to use the tool, though it does not explicitly mention when to use alternatives or exclude other scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage and build advanced filters for tasks and projects with validation
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | ||
| parameters | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits. It mentions 'validation' but does not clarify whether operations are destructive, require authentication, or have side effects. The term 'manage' is vague and fails to specify what happens during create, update, or delete actions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise, but it lacks structure and does not front-load critical information. While not verbose, it is too terse to be fully informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has two parameters with an enum of seven actions and no output schema, the description is incomplete. It does not explain what each action does, what parameters are required for each, or what the tool returns. It falls short of providing sufficient context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the schema provides no parameter details. The description does not explain the 'action' enum values or the structure of the 'parameters' object. It adds no meaning beyond what the schema already conveys.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: managing and building advanced filters for tasks and projects, with validation. This distinguishes it from sibling tools like vikunja_tasks or vikunja_projects, as no other tool is dedicated to filters. The verb 'manage and build' combined with the resource 'advanced filters' makes the purpose specific and actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like vikunja_tasks or vikunja_projects. It does not mention prerequisites, exclusions, or criteria for choosing between the seven actions listed in the schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage task labels with full CRUD operations for organizing and categorizing tasks
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | ||
| page | No | ||
| title | No | ||
| search | No | ||
| perPage | No | ||
| hexColor | No | ||
| subcommand | Yes | ||
| description | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It only states 'full CRUD operations,' which implies mutability but does not disclose if operations like delete are destructive, if updates are idempotent, or any auth or rate limit behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise. However, given the tool's complexity (8 parameters, CRUD operations), it is underspecified and fails to earn its space by omitting crucial usage details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 8 parameters, no output schema, and no annotations, the description is severely incomplete. It does not explain how to use the subcommand enum or which parameters apply to which operation, leaving the agent without sufficient context to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides no information about any of the 8 parameters. Schema description coverage is 0%, so the description does not add any meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool manages task labels with full CRUD operations, which is a specific verb (manage) and resource (task labels). It distinguishes from siblings like vikunja_task_labels by implying this is about the labels themselves, not their assignment to tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus sibling tools like vikunja_task_labels or vikunja_projects. There is no mention of prerequisites, context, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage projects with full CRUD operations, hierarchy management, and sharing capabilities
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | ||
| name | No | ||
| page | No | ||
| right | No | ||
| title | No | ||
| search | No | ||
| shares | No | ||
| perPage | No | ||
| shareId | No | ||
| hexColor | No | ||
| maxDepth | No | ||
| password | No | ||
| projectId | No | ||
| sessionId | No | ||
| shareHash | No | ||
| isArchived | No | ||
| subcommand | Yes | ||
| description | No | ||
| includeArchived | No | ||
| parentProjectId | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It lists capabilities but does not mention that operations like delete or archive are destructive, require authentication, or have side effects. The description is too high-level.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but sacrifices important detail. It could be expanded with structured information about subcommands without being overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (20 parameters, many subcommands, no output schema), the description is woefully incomplete. It does not explain the subcommand enum, required parameters, or return values, making it hard for the AI to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 20 parameters with 0% coverage (no descriptions). The description fails to explain any parameters, such as how subcommand selects the action or the meaning of id, projectId, etc. This leaves the AI without crucial context for proper invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it manages projects with CRUD, hierarchy, and sharing, which matches the subcommand enum. It distinguishes from sibling tools by specifying 'projects', which are a different resource than tasks, buckets, labels, etc. However, it could be more specific about what 'manage' entails.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like vikunja_task_crud or vikunja_bucket. The description does not provide any context about prerequisites or scenarios where this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage task assignments: assign users, unassign users, list assignees
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| assignees | No | ||
| operation | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It implies mutation for assign/unassign but does not disclose side effects (e.g., overwrite vs. additive assignment), permission requirements, or idempotency. The 'list assignees' operation is read-only, but the description lumps it with mutations without clarifying behavioral differences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise but sacrifices completeness. It front-loads the purpose but lacks detail on behavior and parameters. It could be restructured to include parameter hints without significantly increasing length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema, the description needs to explain return values or results. It does not mention what the tool returns for each operation, error conditions (e.g., invalid task ID), or required pre-existing state (e.g., an authenticated session). For a tool with 3 parameters and explicit operations, the description is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only loosely maps to parameters: 'assign users, unassign users, list assignees' corresponds to the 'operation' enum but does not explain the 'id' (task ID?) or 'assignees' (user IDs?) parameters. This leaves ambiguity about parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Manage task assignments: assign users, unassign users, list assignees' clearly specifies the resource (task assignees) and the three distinct operations. While it does not explicitly differentiate from sibling tools like vikunja_task_crud, the tool name and operations provide sufficient clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no guidance on when to use this tool versus alternatives (e.g., vikunja_task_crud). It does not state prerequisites, such as needing an existing task, or exclude scenarios where other tools are more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage bulk task operations: create, update, delete multiple tasks
| Name | Required | Description | Default |
|---|---|---|---|
| field | No | ||
| tasks | No | ||
| value | No | ||
| taskIds | No | ||
| operation | Yes | ||
| projectId | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It only states generic operations but omits critical behavioral details: atomicity of bulk operations, partial failure handling, authentication scoping, or whether updates merge or replace. A bulk tool needs more transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single short sentence, no fluff, but could be restructured to front-load key info. Adequate length but missing critical details, so not perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 parameters, no output schema, and no annotations, the description is severely incomplete. It does not cover return values, prerequisites, error handling, or how input parameters map to operations. Insufficient for an agent to reliably invoke.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% – description adds no explanation for any of the 6 parameters. For example, 'field' and 'value' are cryptic, and 'operation' enum values are not explicitly mapped to the listed operations. Schema structure exists but description fails to clarify usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'Manage bulk task operations: create, update, delete multiple tasks', clearly identifying the verb (manage bulk operations) and resource (tasks). This distinguishes it from siblings like vikunja_task_crud (single task) and vikunja_tasks (list).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this bulk tool versus the many sibling tools for specific operations (e.g., vikunja_task_labels, vikunja_task_assignees). The description lacks context for choosing between bulk and single operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage task comments: add a comment, or list a task's comments
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| comment | No | ||
| commentId | No | ||
| operation | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. It only mentions basic operations (add, list) but does not disclose whether comments can be edited, deleted, or if there are prerequisites like authentication or existing tasks. The schema's lack of requirement for 'comment' field when operation='comment' further obscures behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 12 words, which is very concise. However, this brevity sacrifices important details about parameters and operation-specific requirements, making it less helpful than it could be.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 4 parameters, no output schema, and no annotations, the description is incomplete. It fails to clarify parameter roles for each operation, leading to confusion. For a tool with two distinct actions, more context is needed to ensure correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must explain parameters. The description mentions adding comments (implying 'comment' field) and listing (implying 'id' for task), but does not explain 'commentId' parameter, nor that 'comment' is effectively required for 'comment' operation. This leaves critical gaps for proper invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool manages task comments with two specific operations: adding a comment and listing comments. It distinguishes from sibling tools that handle other task attributes like labels or assignees.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives. While it is implied for comment management, there are no conditions or exclusions mentioned, leaving the agent to infer from sibling names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage individual tasks: create, get, update, delete, list
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | ||
| done | No | ||
| page | No | ||
| sort | No | ||
| title | No | ||
| filter | No | ||
| labels | No | ||
| search | No | ||
| dueDate | No | ||
| perPage | No | ||
| filterId | No | ||
| priority | No | ||
| assignees | No | ||
| operation | Yes | ||
| projectId | No | ||
| sessionId | No | ||
| repeatMode | No | ||
| allProjects | No | ||
| description | No | ||
| repeatAfter | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only states it manages tasks, but does not explain what each operation does, required permissions, side effects, or constraints (e.g., whether deletion is irreversible, or prerequisites like authentication).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short, which could be seen as concise, but it omits critical details needed for usage. It is under-specified rather than efficiently documented.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of 20 parameters, no output schema, and no annotations, the description fails to provide sufficient context. An agent cannot determine required parameters per operation, expected outputs, or error conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the description adds no information about the 20 parameters. The description merely lists operations but does not specify which parameters apply to which operation, their formats, or purpose. This severely hinders correct tool invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description lists the operations (create, get, update, delete, list) and identifies the resource as 'individual tasks'. However, it does not differentiate from sibling tools like vikunja_tasks or vikunja_task_assignees, which also deal with tasks. The purpose is clear but not distinct enough contextually.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. For example, the sibling tool 'vikunja_task_assignees' might be better for managing assignees, but there is no mention of when to choose one over the other.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage task labels: apply, remove, list labels
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| labels | No | ||
| operation | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must disclose behavioral traits. It lists three operations but fails to explain side effects, error conditions (e.g., what happens if a label doesn't exist, or if removing a label that isn't applied), or idempotency. The description is too minimal to convey expected behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (one sentence), which is concise. However, it sacrifices clarity by being too minimal. It could be restructured to front-load the task context and clarify parameter usage without adding much length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters and no output schema or annotations, the description should provide sufficient context for correct invocation. It does not explain which parameters are required for each operation (e.g., 'labels' is required for apply and remove but not for list). Additionally, it doesn't mention that label IDs must exist (likely created via 'vikunja_labels'). Incomplete for practical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should compensate. It merely lists operations without explaining parameter meaning. For instance, it doesn't specify that 'id' refers to the task ID, or that 'labels' is an array of label IDs relevant only for 'apply-label' and 'remove-label'. The description adds little value beyond the parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Manage task labels: apply, remove, list labels' clearly indicates the tool is for operations on task labels. It lists three specific operations. However, it could more explicitly state that it operates on a specific task (via the 'id' parameter) to better distinguish from 'vikunja_labels' which manages labels globally.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus siblings. For example, it doesn't clarify that this tool associates labels with tasks, while 'vikunja_labels' is for creating/deleting labels themselves. No preconditions or context for each operation are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage task relationships: relate tasks, unrelate tasks, list relations
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| operation | Yes | ||
| otherTaskId | No | ||
| relationKind | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided. The description does not disclose behavioral traits such as idempotency, side effects (e.g., whether unrelating is destructive), permissions required, or rate limits. It only lists operations without clarifying behavioral implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very brief (one sentence). While it is concise, it sacrifices necessary detail. It adequately front-loads the purpose but omits important structural elements.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema, no annotations, and the complexity of task relationships (multiple relation types), the description is severely incomplete. It does not explain how to list relations, what response to expect, or how to properly use the relationship kinds.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. However, it only names operations (relate, unrelate, relations) without explaining how parameters like 'otherTaskId' or 'relationKind' should be used. The meaning of the 'relationKind' enum values is not clarified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs and resource: 'Manage task relationships: relate tasks, unrelate tasks, list relations'. It clearly distinguishes the tool from sibling tools like vikunja_task_assignees or vikunja_task_comments by explicitly naming the domain of task relationships.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs. alternatives. It does not specify prerequisites, conditions, or scenarios where other tools would be more appropriate. The description lacks usage context entirely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage task reminders: add, remove, list reminders
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | ||
| operation | Yes | ||
| reminderId | No | ||
| reminderDate | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only mentions the operations without disclosing side effects, error handling, or permission requirements. For example, it does not state that 'add-reminder' is a write operation or what happens when removing a non-existent reminder.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one sentence, which is concise, but it is also under-specified. It could be restructured to front-load key information, such as stating that 'id' is the task ID.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (4 parameters, no output schema, no annotations), the description is severely incomplete. It does not clarify relationships between parameters, required fields per operation, or return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any parameter. It fails to map operations to required parameters (e.g., that 'add-reminder' requires reminderDate). The description adds no value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the resource (task reminders) and operations (add, remove, list). It is clear and distinguishes tool from siblings like vikunja_task_crud or vikunja_task_assignees. It could be improved by explicitly stating that the 'id' parameter refers to a task ID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor on prerequisites or exclusions. The description only lists operations without context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage tasks with comprehensive operations (create, update, delete, list, assign, attach files, comment, bulk operations)
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | ||
| done | No | ||
| page | No | ||
| sort | No | ||
| field | No | ||
| tasks | No | ||
| title | No | ||
| value | No | ||
| filter | No | ||
| labels | No | ||
| search | No | ||
| comment | No | ||
| dueDate | No | ||
| perPage | No | ||
| taskIds | No | ||
| filterId | No | ||
| priority | No | ||
| assignees | No | ||
| commentId | No | ||
| projectId | No | ||
| sessionId | No | ||
| reminderId | No | ||
| repeatMode | No | ||
| subcommand | Yes | ||
| allProjects | No | ||
| description | No | ||
| otherTaskId | No | ||
| repeatAfter | No | ||
| relationKind | No | ||
| reminderDate | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description gives no behavioral traits (e.g., idempotency, side effects, permissions). The tool could be destructive or require specific conditions, but nothing is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with one sentence, but it sacrifices substance for brevity. It is not verbose, but it fails to provide necessary details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 30 parameters, 22 subcommands, and numerous sibling tools, the description is critically incomplete. It lacks parameter explanations, output schema, and usage context, leaving the agent severely underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no information about the 30 parameters. Parameters like subcommand, id, and filters are left unexplained, making it impossible for an agent to use them correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool manages tasks with comprehensive operations, but it does not clarify how it differs from specialized siblings like vikunja_task_assignees, vikunja_task_crud, etc. The purpose is vague and overlapping.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus sibling tools. There is no mention of alternatives or exclusions, leaving the agent to guess the appropriate context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage teams and team memberships for collaborative project management
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | ||
| name | No | ||
| page | No | ||
| admin | No | ||
| search | No | ||
| userId | No | ||
| perPage | No | ||
| subcommand | Yes | ||
| description | No | ||
| memberSubcommand | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description fails to disclose behavioral traits such as mutation, authorization requirements, or side effects. For a tool that can create, update, and delete teams, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise but omits critical information. It front-loads the resource but does not earn its place due to lack of useful detail beyond a vague statement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (10 parameters, CRUD operations, no output schema), the description is grossly incomplete. It fails to explain subcommands, parameter combinations, member management, or return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 10 parameters with 0% description coverage, and the tool description does not explain any of them. The agent cannot infer what 'id', 'name', 'subcommand', or other parameters do without additional context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Manage teams and team memberships', which identifies the resource but uses the vague verb 'manage'. It does not specify the scope of operations, nor does it differentiate from sibling tools like vikunja_task_crud or vikunja_labels. The purpose is somewhat clear but lacks specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus its siblings. The description gives no context about prerequisites, exclusions, or typical use cases for team management.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage task templates for creating consistent tasks and project structures
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | ||
| name | No | ||
| tags | No | ||
| projectId | No | ||
| variables | No | ||
| subcommand | Yes | ||
| description | No | ||
| projectName | No | ||
| parentProjectId | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose behavioral traits such as whether the tool is destructive, read-only, or requires authentication. The description carries the full burden but fails to provide any transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
While the description is only one sentence and front-loaded, it is too sparse and lacks meaningful content for a tool with 9 parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (9 parameters, no output schema, no annotations), the description is extremely incomplete. A tool managing templates needs to explain subcommands, parameter usage, and return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain any of the 9 parameters. With 0% schema description coverage, the description should compensate, but it adds no parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the vague verb 'manage', not specifying whether it creates, lists, updates, or deletes templates. It does not distinguish from sibling tools like vikunja_task_crud or vikunja_projects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. No context about prerequisites or use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage webhooks for integrating Vikunja events with external services
| Name | Required | Description | Default |
|---|---|---|---|
| events | No | ||
| secret | No | ||
| projectId | No | ||
| targetUrl | No | ||
| webhookId | No | ||
| subcommand | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It only states 'manage webhooks' without disclosing behavioral traits like authentication needs or side effects of create/delete operations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise but under-informative for a tool with 6 parameters and multiple subcommands. It could be more efficient by including key actions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (6 parameters, no output schema, no annotations), the description is insufficient. It explains neither the subcommand variants nor parameter dependencies.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no meaning beyond the schema. With 0% schema description coverage, the agent gets no help understanding parameters like events, secret, or subcommand options.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states it manages webhooks for integrating events with external services, which is clear. However, it does not specify that it covers CRUD and list-events subcommands, making it slightly less precise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. The name and sibling tools imply purpose, but explicit differentiation is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The 'vikunja_tasks' tool description claims to handle all task operations, overlapping with many specialized tools like vikunja_task_crud, vikunja_task_assignees, vikunja_task_comments, etc. This creates significant ambiguity about which tool to use for task-related actions, leading to potential misselection.
All tools share the 'vikunja_' prefix, but the suffix naming is inconsistent: some use plain nouns (auth, filters, projects), while tasks have a mix of 'vikunja_tasks' and 'vikunja_task_*'. The plural 'tasks' vs singular 'task' adds inconsistency, though overall the pattern is still readable.
With 17 tools, the count is slightly above the typical 3-15 well-scoped range. The duplication due to the overlapping 'vikunja_tasks' tool makes the set feel heavier than necessary, but for a full-featured task management server, 17 tools could be justified if each had a distinct role.
The tool surface covers authentication, projects, tasks (with comments, labels, relations, reminders, bulk operations), teams, templates, webhooks, and filters. It addresses most lifecycle operations for the domain, though the redundancy suggests some consolidation could be possible.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Create and manage MeisterTask projects, tasks, and notes from your AI assistant.
Manage tasks, Focus Zone, notes, projects, and task history from compatible AI assistants.
Manage Superlist tasks and lists in plain language from any MCP-compatible AI agent.
Official Todoist MCP server for AI assistants to manage tasks, projects, and workflows.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/4nm1tsu/vikunja-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
