Donetick MCP Server

Сервер Model Context Protocol (MCP) для управления задачами Donetick. Позволяет Claude и другим AI-ассистентам, совместимым с MCP, взаимодействовать с вашим экземпляром Donetick через API с ограничением скорости.

Возможности

• 16 инструментов MCP: Полное управление задачами (список, получение, создание, завершение, обновление, удаление, пропуск), организация меток (список, создание, обновление, удаление), информация об участниках круга, управление пользователями (список пользователей круга, получение профиля пользователя)

• Полная интеграция с API: Использует Donetick Full API (/api/v1/) со всеми конечными точками, правильно настроенными с завершающими слешами

• Поддержка всех полей: Все 26+ полей создания задач работают, включая метаданные частоты, скользящие расписания, несколько исполнителей, стратегии назначения, уведомления, метки, приоритет, баллы, подзадачи и многое другое

• Единообразный регистр полей: Поля в camelCase везде (name, description, dueDate, createdBy и т.д.)

• Специализированные инструменты обновления: Обновление деталей задачи, приоритета и исполнителя с помощью выделенных конечных точек

• JWT-аутентификация: Автоматическое управление токенами с прозрачным обновлением

• Умное кэширование: Интеллектуальное кэширование для операций get_chore (TTL 60 секунд по умолчанию)

• Ограничение скорости: Алгоритм token bucket предотвращает перегрузку API

• Логика повторных попыток: Экспоненциальная задержка с джиттером для устойчивых операций

• Async/Await: Неблокирующие операции с использованием httpx

• Валидация входных данных: Валидаторы полей Pydantic с очисткой

• Усиленная безопасность: Принудительное использование HTTPS, очищенное логирование, безопасные сообщения об ошибках, безопасность JWT-токенов

• Поддержка Docker: Контейнеризированное развертывание с лучшими практиками безопасности

• Всестороннее тестирование: Мокированные модульные/интеграционные тесты + фреймворк для тестирования живого API с pytest

• Безопасность типов: Модели Pydantic для валидации запросов/ответов

Быстрый старт

Самая простая установка (Claude Code CLI):

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

Затем настройте свои учетные данные Donetick при появлении запроса.

Или установите вручную с помощью 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"
      }
    }
  }
}

Преимущества:

• ✅ Не требует установки — запускается напрямую из PyPI

• ✅ Автообновление с флагом --refresh

• ✅ Изолированная среда — нет конфликтов

• ✅ Работает на Windows, macOS, Linux

Требования

• Экземпляр Donetick (самостоятельно размещенный или облачный)

• Учетные данные Donetick (имя пользователя и пароль)

• Для метода uvx: установленный uv (см. Быстрый старт)

• Для других методов: Python 3.11 или выше

Установка

Вариант 1: uvx (рекомендуется — установка не требуется)

См. Быстрый старт выше.

Флаг --refresh гарантирует, что вы всегда получаете последнюю версию при перезапуске Claude Desktop.

Вариант 2: Docker

1. Клонируйте репозиторий:

   git clone https://github.com/jason1365/donetick-mcp-server.git
   cd donetick-mcp-server

2. Создайте файл .env:

   cp .env.example .env
   # Edit .env with your configuration

3. Настройте переменные окружения:

   DONETICK_BASE_URL=https://your-instance.com
   DONETICK_USERNAME=your_username
   DONETICK_PASSWORD=your_password
   LOG_LEVEL=INFO

4. Соберите и запустите:

   docker-compose build
   docker-compose up -d

Вариант 3: pip install (для системной интеграции)

Если вы хотите установить глобально или в виртуальное окружение:

# Install from PyPI
pip install donetick-mcp-server

# Or install for development
git clone https://github.com/jason1365/donetick-mcp-server.git
cd donetick-mcp-server
pip install -e .

# Run the server
donetick-mcp-server
# Or: python -m donetick_mcp.server

Затем настройте Claude Desktop для использования установленной команды:

{
  "mcpServers": {
    "donetick": {
      "command": "donetick-mcp-server",
      "env": {
        "DONETICK_BASE_URL": "https://your-instance.com",
        "DONETICK_USERNAME": "your_username",
        "DONETICK_PASSWORD": "your_password"
      }
    }
  }
}

Аутентификация

Сервер MCP использует JWT-аутентификацию с вашими учетными данными Donetick.

Что вам нужно:

• Ваше имя пользователя Donetick (то же, что и для веб-входа)

• Ваш пароль Donetick (тот же, что и для веб-входа)

Как это работает:

1. Сервер входит в систему с вашими учетными данными при запуске

2. JWT-токен получен и хранится в памяти

3. Токен автоматически обновляется до истечения срока действия

4. Ручное управление токенами не требуется

Безопасность:

• Учетные данные хранятся только в переменных окружения или файле .env

• JWT-токены хранятся только в памяти (никогда не сохраняются на диск)

• Автоматическое обновление токена предотвращает истечение сессии

• Для всех соединений требуется HTTPS

Интеграция с Claude Desktop

Самый простой способ — Claude Code CLI:

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

Или отредактируйте файл конфигурации вручную:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

Конфигурация uvx (рекомендуется)

{
  "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"
      }
    }
  }
}

Примечание: Флаг --refresh автоматически обновляет до последней версии.

Конфигурация Docker

{
  "mcpServers": {
    "donetick": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "donetick-mcp-server",
        "python",
        "-m",
        "donetick_mcp.server"
      ]
    }
  }
}

Конфигурация pip install

{
  "mcpServers": {
    "donetick": {
      "command": "donetick-mcp-server",
      "env": {
        "DONETICK_BASE_URL": "https://your-instance.com",
        "DONETICK_USERNAME": "your_username",
        "DONETICK_PASSWORD": "your_password"
      }
    }
  }
}

После обновления конфигурации перезапустите Claude Desktop.

Доступные инструменты

1. list_chores

Вывести список всех задач с возможностью фильтрации.

Параметры:

• filter_active (boolean, необязательно): Фильтр по статусу активности

• assigned_to_user_id (integer, необязательно): Фильтр по ID назначенного пользователя

Пример:

List all active chores assigned to me

2. get_chore

Получить детали конкретной задачи по ID.

Параметры:

• chore_id (integer, обязательно): ID задачи

Пример:

Show me details of chore 123

3. create_chore

Создать новую задачу с полной поддержкой конфигурации.

Основные параметры:

• name (string, обязательно): Название задачи (1-200 символов)

• description (string, необязательно): Описание задачи (макс. 5000 символов)

• due_date (string, необязательно): Дата выполнения в формате YYYY-MM-DD или RFC3339

• created_by (integer, необязательно): ID пользователя-создателя

Параметры повторения/частоты:

• frequency_type (string, необязательно): Как часто повторяется задача — "once", "daily", "weekly", "monthly", "yearly", "interval_based" (по умолчанию: "once")

• frequency (integer, необязательно): Множитель частоты, например, 1=еженедельно, 2=раз в две недели (по умолчанию: 1)

• frequency_metadata (object, необязательно): Дополнительная конфигурация частоты, например {"days": [1,3,5], "time": "09:00"}

• is_rolling (boolean, необязательно): Скользящее расписание (следующий срок на основе завершения) vs фиксированное (по умолчанию: false)

Параметры назначения пользователей:

• assigned_to (integer, необязательно): ID основного назначенного пользователя

• assignees (array, необязательно): Несколько исполнителей в виде [{"userId": 1}, {"userId": 2}]

• assign_strategy (string, необязательно): Стратегия назначения — "least_completed", "round_robin", "random" (по умолчанию: "least_completed")

Параметры уведомлений:

• notification (boolean, необязательно): Включить уведомления (по умолчанию: false)

• nagging (boolean, необязательно): Включить напоминания (по умолчанию: false)

• predue (boolean, необязательно): Включить уведомления до наступления срока (по умолчанию: false)

Параметры организации:

• priority (integer, необязательно): Уровень приоритета 1-5 (1=самый низкий, 5=самый высокий)

• labels (array, необязательно): Метки-теги, например ["cleaning", "outdoor"]

Параметры статуса:

• is_active (boolean, необязательно): Статус активности — неактивные задачи скрыты (по умолчанию: true)

• is_private (boolean, необязательно): Приватная задача, видимая только создателю (по умолчанию: false)

Параметры геймификации:

• points (integer, необязательно): Баллы, начисляемые за выполнение

Расширенные параметры:

• sub_tasks (array, необязательно): Подзадачи/элементы контрольного списка

Примеры:

Create a simple one-time chore:
Create a chore called "Take out trash" due on 2025-11-10

Create a recurring chore with notifications:
Create a weekly chore "Clean kitchen" every Monday at 9am with priority 4,
enable nagging notifications, and assign it to user 1

Create an advanced chore:
Create a chore "Grocery shopping" that repeats weekly on Mondays and Wednesdays,
assign to users 1 and 2 using round robin strategy, with priority 3,
labels "shopping" and "outdoor", and award 10 points

4. complete_chore

Отметить задачу как выполненную.

Параметры:

• chore_id (integer, обязательно): ID задачи

• completed_by (integer, необязательно): ID пользователя, выполнившего задачу

Пример:

Mark chore 123 as complete

5. delete_chore

Удалить задачу навсегда. Только создатель может удалить.

Параметры:

• chore_id (integer, обязательно): ID задачи

Пример:

Delete chore 123

6. get_circle_members

Получить всех участников вашего круга (домохозяйства/команды). Показывает, кому вы можете назначать задачи.

Параметры: Нет

Возвращает:

• ID пользователя

• Имя пользователя

• Отображаемое имя

• Роль (admin/member)

• Статус активности

• Баллы и использованные баллы

Пример:

Show me who's in my household
Who can I assign chores to?
List all circle members

Конфигурация

Переменные окружения

Ограничение скорости

Сервер реализует ограничитель скорости на основе token bucket для предотвращения перегрузки API:

• По умолчанию: 10 запросов в секунду с емкостью всплеска 10

• Консервативно: Начинает консервативно и может быть увеличено в зависимости от вашего экземпляра Donetick

• Уважает 429: Автоматически снижает скорость при ограничении со стороны API

Логика повторных попыток

• Экспоненциальная задержка с джиттером для временных сбоев

• Максимум 3 повторные попытки для большинства операций

• Умные повторные попытки: Повторяет только при ошибках 5xx и 429 (ограничение скорости)

• Без повторных попыток на 4xx: Ошибки клиента завершаются немедленно (кроме 429)

Разработка

Запуск тестов

Мокированные тесты (быстро, не требуется экземпляр Donetick):

# Install dev dependencies
pip install -e ".[dev]"

# Run all tests (unit + integration with mocks)
pytest

# Run with coverage
pytest --cov=donetick_mcp --cov-report=html

# Run specific test file
pytest tests/test_client.py
pytest tests/test_server.py

# Run with verbose output
pytest -v

Тесты живого API (требуется экземпляр Donetick):

# Create .env file with credentials (see Configuration section)
# Then run live API integration tests
pytest tests/integration/test_live_api.py -v

# Skip live tests
pytest -m "not live_api"

# Run only live tests
pytest -m live_api

Детали покрытия тестами:

• Мокированные тесты проверяют логику, поведение повторных попыток, ограничение скорости, обработку ошибок

• Тесты живого API проверяют маршрутизацию конечных точек, совместимость регистра полей, форматы ответов

• Полное покрытие гарантирует как надежность клиента API, так и корректность инструментов MCP

Структура проекта

donetick-mcp-server/
├── src/donetick_mcp/
│   ├── __init__.py
│   ├── server.py          # MCP server implementation
│   ├── client.py           # Donetick API client
│   ├── models.py           # Pydantic data models
│   └── config.py           # Configuration management
├── tests/
│   ├── test_client.py      # API client tests
│   └── test_server.py      # MCP server tests
├── tmp/                    # Temporary files (gitignored)
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml
└── README.md

Примечание: Директория tmp/ используется для временных тестовых скриптов и файлов анализа во время разработки. Она игнорируется git и не включается в релизы.

Документация API

Этот сервер использует Donetick Full API (/api/v1/) с JWT-аутентификацией.

Официальные ресурсы

• Документация Donetick: https://docs.donetick.com/

• GitHub Donetick: https://github.com/donetick/donetick

Архитектура API

Используемые конечные точки:

• Список задач: GET /api/v1/chores/ (требуется завершающий слеш)

• Получить задачу: GET /api/v1/chores/{id} (включает подзадачи)

• Создать задачу: POST /api/v1/chores/

• Обновить задачу: PUT /api/v1/chores/{id} (name, description, nextDueDate)

• Обновить приоритет: PUT /api/v1/chores/{id}/priority

• Обновить исполнителя: PUT /api/v1/chores/{id}/assignee

• Пропустить задачу: PUT /api/v1/chores/{id}/skip

• Завершить задачу: POST /api/v1/chores/{id}/do

• Удалить задачу: DELETE /api/v1/chores/{id}

• Получить участников: GET /api/v1/circles/members/ (требуется завершающий слеш)

Важно: Конечные точки списка требуют завершающих слешей (/api/v1/chores/, /api/v1/circles/members/). Это обрабатывается автоматически клиентом.

Важные замечания

1. Используется Full API: Не внешний API (eAPI) — используется внутренний Full API

2. Регистр полей: Единообразный camelCase везде (name, description, dueDate, createdBy)

3. Завершающие слеши: Конечные точки списка включают завершающие слеши для правильной маршрутизации

4. Аутентификация: JWT Bearer токены с автоматическим управлением

5. Полная поддержка функций: Доступны все 26+ полей создания задач

6. Автоматическое обновление токена: JWT-токены обновляются прозрачно

7. В рамках круга: Все операции ограничены вашим кругом (домохозяйство/команда)

8. Без премиум-ограничений: Все функции доступны через полный API

Устранение неполадок

Частые проблемы

"DONETICK_BASE_URL environment variable is required"

• Убедитесь, что ваш файл .env существует и правильно отформатирован

• Для Docker: убедитесь, что переменные окружения переданы в docker-compose.yml

"Rate limited, waiting..."

• Сервер соблюдает ограничения скорости API

• Рассмотрите возможность уменьшения RATE_LIMIT_PER_SECOND, если это происходит часто

"Connection refused" или ошибки тайм-аута

• Проверьте, что URL вашего экземпляра Donetick правильный

• Убедитесь, что ваш экземпляр Donetick доступен

• Проверьте, что правила брандмауэра разрешают исходящие соединения

"401 Unauthorized" или "Invalid credentials"

• Убедитесь, что ваше имя пользователя и пароль верны

• Проверьте, что ваша учетная запись не заблокирована и не отключена

• Убедитесь, что вы можете войти в веб-интерфейс Donetick с теми же учетными данными

• Проверьте наличие опечаток в переменных окружения

Инструменты не отображаются в Claude

• Перезапустите Claude Desktop после изменений в конфигурации

• Проверьте логи Claude Desktop на наличие ошибок

• Убедитесь, что путь к файлу конфигурации указан правильно

Отладка

Включите отладочное логирование:

export LOG_LEVEL=DEBUG

Или в Docker:

environment:
  - LOG_LEVEL=DEBUG

Просмотр логов Docker:

docker-compose logs -f donetick-mcp

Безопасность

• Учетные данные: Никогда не сохраняйте учетные данные в системе контроля версий (используйте файл .env)

• JWT-токены: Хранятся только в памяти, никогда не записываются на диск

• Автоматическое обновление токена: Предотвращает истечение сессии без участия пользователя

• Изоляция Docker: Запускается от непривилегированного пользователя в контейнере

• Ограничения ресурсов: Ограничения по памяти и ЦП предотвращают истощение ресурсов

• Валидация входных данных: Модели Pydantic проверяют все входные данные

• Обязательный HTTPS: Сервер требует HTTPS для всех подключений к Donetick

Участие в разработке

Вклад приветствуется! Пожалуйста:

1. Сделайте форк репозитория

2. Создайте ветку для новой функции

3. Добавьте тесты для новой функциональности

4. Убедитесь, что все тесты проходят

5. Отправьте pull request

Лицензия

Лицензия MIT — подробности в файле LICENSE

Благодарности

• Donetick — Открытое приложение для управления задачами

• Model Context Protocol — Спецификация MCP

• Anthropic — MCP SDK и Claude

Поддержка

• Проблемы: https://github.com/jason1365/donetick-mcp-server/issues

• Документация Donetick: https://docs.donetick.com

• Документация MCP: https://modelcontextprotocol.io

Сделано с ❤️ для сообществ Donetick и MCP