AI 보조자가 Vikunja 작업 관리 인스턴스와 상호작용할 수 있도록 하는 모델 컨텍스트 프로토콜(MCP) 서버입니다.

특징

• 직관적인 AI 상호작용을 위한 서브커맨드 기반 도구
• 자동 토큰 관리가 포함된 세션 기반 인증
• 전체 작업 관리 연산 구현
• CRUD 운영을 포함한 완전한 프로젝트 관리
• 라벨 관리 작업 조직
• 협업을 위한 팀 운영 (API에 의해 제한된 멤버 획득/업데이트/멤버)
• 설정 및 검색 포함 사용자 관리
• 프로젝트 자동화를 위한 웹훅 관리
• **CSV 또는 JSON 파일에서 작업 배치 가져오기
• 날짜, ID, 육진수 색상에 대한 입력 검증
• 할당자를 위한 효율적인 diff 기반 업데이트
• 타입 안전을 위한 엄격한 모드가 적용된 TypeScript
• 타이핑 오류와 중앙 집중식 유틸리티를 통한 종합적 오류 처리
• 복원력을 위한 주머니섬 차단기를 적용한 생산 준비 가능한 재시도 로직
• Zod 기반 입력 검증 및 DoS 보호를 통한 향상된 보안
• DoS 공격에 대한 속도 제한 보호를 설정할 수 있는 제한
• 페이지네이션 제한과 사용 모니터링이 포함된 메모리 보호

Vikunja MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to interact with Vikunja task management instances.

Features

• 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

🚀 Major Architectural Improvements (v0.2.0)

This release represents a massive architectural simplification that eliminates technical debt while enhancing security and reliability:

Storage Architecture Refactoring (90% Code Reduction)

• 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

Zod-Based Filter System (850+ Lines Removed)

• 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

Production-Ready Retry System (580+ Lines Replaced)

• 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

Zero Breaking Changes

All improvements maintain 100% backward compatibility with existing implementations while providing enhanced reliability and security.

Requirements

• Node.js 20+ (LTS versions only)
• Vikunja instance with API access
• API token (starting with tk_) or JWT token for authentication

Installation

Option 1: Install from NPM (Recommended)

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