amazing-marvin-mcp

Обзор

Неофициальный MCP-сервер для Amazing Marvin, позволяющий ассистенту вроде Claude отвечать на вопросы «что у меня во входящих?», «что нужно сделать на этой неделе?», «я в машине, чем я могу заняться?» и действовать: переименовывать, менять метки, переносить, перемещать, разбивать на проекты, сохранять исследования в заметку.

Этот проект не связан с Amazing Marvin, не одобрен и не поддерживается им; он использует их публичный API.

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

Claude ──MCP (stdio)──▶ amazing-marvin-mcp
                          ├─ local mirror ◀── CouchDB `_changes` (your sync database)
                          │    reads, search and filters run here: no rate-limit cost
                          └─ writes ──▶ Marvin REST API (addTask, doc/update, markDone)
                                        throttled to Marvin's limits (1 request / 3 s)

У REST API Marvin нет конечной точки «список» или «поиск», а дневной лимит составляет 1440 запросов, поэтому чтение идёт из локальной копии вашей базы данных, которую поддерживает в актуальном состоянии инкрементальный опрос _changes (не чаще раза в минуту). Запись идёт через REST API, который обрабатывает учёт разрешения конфликтов Marvin (fieldUpdates) на стороне сервера.

Что знает ассистент

• Семантику Marvin — словами самого интерфейса. Входящие = не отнесено никуда; категории и проекты вкладываются произвольно (Мастер-список). Четыре даты различаются: дата выполнения (день, на который вы планируете задачу, «запланировано»), срок (жёсткий внешний дедлайн), дата окончания (самостоятельно установленная цель; запланированная неделя/месяц в Planning Ahead — более мягкая форма), дата начала (до неё задача скрыта в Backburner). Плюс оценки длительности (в минутах), важность (звёзды P1–P3), Eat-the-Frog, Backburner, метки и группы меток.

• Вашу структуру (get_structure): дерево категорий/проектов с идентификаторами и количеством открытых задач, метки по группам и какие стратегии Marvin у вас включены (по их названиям на экране Strategies).

• Ваш рабочий процесс (workflow.md или каталог workflow/ с разделами): как вы используете Marvin: что означают метки, как вы планируете, ваш чек-лист разбора входящих, что значит «быстрая победа». Marvin гибок, поэтому именно это позволяет ассистенту действовать так, как действовали бы вы. Он внедряется в инструкции сервера и доступен как marvin://workflow (и marvin://workflow/<section>).

Инструменты

Инструмента удаления намеренно нет: корзина Marvin работает на стороне клиента, поэтому удаление через API необратимо.

Related MCP server: Amazing Marvin MCP

Установка и настройка (для использования)

1. Установка (требуется uv):

   uv tool install git+https://github.com/tsvikas/amazing-marvin-mcp.git

2. Учётные данные. В Marvin включите стратегию API (Strategies → API → settings). Поместите её значения в ~/.config/amazing-marvin-mcp/.env (Linux; amazing-marvin-mcp check выведет точный путь для вашей ОС):

   MARVIN_API_TOKEN=...           # create / mark done
   MARVIN_FULL_ACCESS_TOKEN=...   # edit existing items; omit for no edits
   MARVIN_SYNC_SERVER=...         # CouchDB: the read mirror
   MARVIN_SYNC_DATABASE=...
   MARVIN_SYNC_USER=...
   MARVIN_SYNC_PASSWORD=...

   Переменные окружения и .env в рабочем каталоге также работают (и переопределяют пользовательский файл). Пока экспериментируете, используйте второй, одноразовый аккаунт Marvin: токен с полным доступом может повредить данные.

3. Проверка и первая синхронизация:

   amazing-marvin-mcp check     # verifies tokens, pulls the database, prints counts

4. Опишите свой рабочий процесс:

   amazing-marvin-mcp init-workflow            # one workflow.md to edit, or
   amazing-marvin-mcp init-workflow --split    # a workflow/ directory: planning, labels, triage, daily…

   Всё, что в нём есть, попадает в инструкции модели (а каждый раздел также является ресурсом marvin://workflow/<section>), поэтому формулируйте кратко и конкретно.

5. Зарегистрируйте сервер в вашем MCP-клиенте.

   Claude Code:

   claude mcp add marvin -- amazing-marvin-mcp serve

   Claude Desktop (claude_desktop_config.json):

   {
     "mcpServers": {
       "marvin": { "command": "amazing-marvin-mcp", "args": ["serve"] }
     }
   }

   Оба читают пользовательский .env, поэтому секреты не попадают в конфигурацию клиента. Затем спросите: «что у меня во входящих Marvin?»

Прочие настройки (показываются командой check): MARVIN_WORKFLOW_FILE (файл или каталог), MARVIN_CACHE_DIR, MARVIN_MIN_REQUEST_INTERVAL (секунды между REST-запросами, по умолчанию 3), MARVIN_MIRROR_MAX_AGE (секунды до повторного опроса при чтении, по умолчанию 60).

Файл зеркала содержит все ваши задачи; он записывается с правами только для владельца в каталоге кэша.

Разработка

git clone https://github.com/tsvikas/amazing-marvin-mcp && cd amazing-marvin-mcp
uv sync && just prepare                     # deps + pre-commit hooks
just test && just lint

Запустите сервер из клона репозитория (.env в корне репозитория игнорируется git и подхватывается, когда клиент запускается из этого каталога; в противном случае используйте -e VAR=value или пользовательский файл):

claude mcp add marvin-dev -- uv run --directory "$PWD" amazing-marvin-mcp serve

tests/test_live.py запускает все инструменты в режиме «из конца в конец» и по умолчанию воспроизводит записанную кассету (tests/cassettes/), которая также служит образцом реальных документов Marvin. Чтобы перезаписать сценарий с одноразовым аккаунтом (он создаёт, а затем удаляет несколько элементов [live]):

MARVIN_API_TOKEN=... MARVIN_FULL_ACCESS_TOKEN=... MARVIN_SYNC_SERVER=... \
MARVIN_SYNC_DATABASE=... MARVIN_SYNC_USER=... MARVIN_SYNC_PASSWORD=... \
uv run pytest tests/test_live.py --record-mode=rewrite

Правила оформления для вклада — в CLAUDE.md.

Участие

Хотите внести вклад? См. CONTRIBUTING.md с инструкциями по настройке и рекомендациями для разработчиков.