Donetick MCP Server

A Model Context Protocol (MCP) server for Donetick chores management. Enables Claude and other MCP-compatible AI assistants to interact with your Donetick instance through a rate-limited API.

Features

• 16 MCP Tools: Complete chore management (list, get, create, complete, update, delete, skip), label organization (list, create, update, delete), circle member information, user management (list circle users, get user profile)
• Full API Integration: Uses Donetick Full API (/api/v1/) with all endpoints properly configured with trailing slashes
• Complete Field Support: All 26+ chore creation fields working including frequency metadata, rolling schedules, multiple assignees, assignment strategies, notifications, labels, priority, points, sub-tasks, and more
• Consistent Field Casing: camelCase fields throughout (name, description, dueDate, createdBy, etc.)
• Specialized Update Tools: Update chore details, priority, and assignee with dedicated endpoints
• JWT Authentication: Automatic token management with transparent refresh
• Smart Caching: Intelligent caching for get_chore operations (60s TTL by default)
• Rate Limiting: Token bucket algorithm prevents API overload
• Retry Logic: Exponential backoff with jitter for resilient operations
• Async/Await: Non-blocking operations using httpx
• Input Validation: Pydantic field validators with sanitization
• Security Hardened: HTTPS enforcement, sanitized logging, secure error messages, JWT token security
• Docker Support: Containerized deployment with security best practices
• Comprehensive Testing: Mocked unit/integration tests + live API test framework with pytest
• Type Safety: Pydantic models for request/response validation

Quick Start

Easiest installation (Claude Code CLI):

claude mcp add donetick uvx donetick-mcp-server@latest

Then configure your Donetick credentials when prompted.

Or install manually with uvx:

# Install uv (one-time setup)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Add to Claude Desktop config
# ~/.config/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "donetick": {
      "command": "uvx",
      "args": ["--refresh", "donetick-mcp-server"],
      "env": {
        "DONETICK_BASE_URL": "https://your-instance.com",
        "DONETICK_USERNAME": "your_username",
        "DONETICK_PASSWORD": "your_password"
      }
    }
  }
}

Benefits: