JMAP MCP сервер

Сервер протокола контекста модели (MCP), предоставляющий инструменты для взаимодействия с почтовыми серверами JMAP (JSON Meta Application Protocol). Создан на базе Deno с использованием клиентской библиотеки @htunnicliff/jmap-jam.

Функции

Инструменты управления электронной почтой

• Поиск писем: Поиск писем по текстовым запросам, фильтрам отправителя/получателя, диапазонам дат и ключевым словам. Все фильтры объединяются логическим И.

• Получение писем: Получение конкретных писем по ID с возможностью выбора свойств.

• Получение цепочек: Получение цепочек писем (истории переписки).

• Пометка писем: Пометка писем как прочитанных/непрочитанных, отмеченных флажком/снятых с флажка.

• Перемещение писем: Перемещение писем между почтовыми ящиками.

• Удаление писем: Окончательное удаление писем.

Управление почтовыми ящиками

• Получение почтовых ящиков: Список всех почтовых ящиков/папок с поддержкой иерархии. Используйте это для поиска ID ящиков, необходимых другим инструментам.

Инкрементальная синхронизация

• Получение изменений писем: Получение ID писем, созданных, обновленных или удаленных с момента предыдущего состояния (отслеживание изменений на основе состояния).

• Получение обновлений поиска: Получение добавлений/удалений в рамках предыдущего поискового запроса с момента его последнего queryState.

Составление писем

• Отправка письма: Составление и отправка новых писем с поддержкой обычного текста и HTML.

• Ответ на письмо: Ответ на существующие письма с автоматической обработкой заголовков и поддержкой функции «ответить всем».

Ключевые возможности

• Полная поддержка JMAP RFC 8620/8621 через jmap-jam

• Комплексная проверка входных данных с помощью схем Zod

• Поддержка пагинации для всех операций со списками

• Инкрементальная синхронизация на основе состояния для эффективного опроса

• Расширенная обработка ошибок и управление соединениями

• Регистрация инструментов на основе возможностей (только чтение, отправка)

• Поддержка TypeScript со строгой типизацией

Related MCP server: bare-mcp

Установка

Плагин Claude Code (рекомендуется)

Установите через маркетплейс плагинов:

/plugin marketplace add wyattjoh/claude-code-marketplace
/plugin install jmap-mcp@wyattjoh-marketplace

Затем настройте необходимые переменные окружения в настройках вашего MCP-сервера.

Предварительные требования

• Deno версии 1.40 или выше

• Почтовый сервер с поддержкой JMAP (например, Cyrus IMAP, Stalwart Mail Server, FastMail)

• Действующие учетные данные для аутентификации JMAP

Настройка

Добавьте следующее в выбранный вами агент:

{
  "mcpServers": {
    "jmap": {
      "type": "stdio",
      "command": "deno",
      "args": [
        "run",
        "--allow-net=api.fastmail.com",
        "--allow-env=JMAP_SESSION_URL,JMAP_BEARER_TOKEN,JMAP_ACCOUNT_ID",
        "jsr:@wyattjoh/jmap-mcp@0.6.3"
      ],
      "env": {
        "JMAP_SESSION_URL": "https://api.fastmail.com/jmap/session",
        "JMAP_BEARER_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}

Замените api.fastmail.com в --allow-net на имя хоста вашего JMAP-сервера, если вы не используете FastMail.

Использование

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

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

get_mailboxes

Список почтовых ящиков/папок с их ID, именами и метаданными. Вызывайте это первым, чтобы получить ID ящиков, необходимые для search_emails (inMailbox) и move_emails (mailboxId). Распространенные имена: Inbox, Drafts, Sent, Trash, Archive, Spam/Junk.

Параметры:

• parentId (необязательно): Фильтр по ID родительского ящика

• limit (необязательно): Максимальное количество результатов (1-200, по умолчанию: 100)

• position (необязательно): Начальная позиция для пагинации

search_emails

Поиск писем с фильтрами. Все фильтры объединяются логическим И. Возвращает только ID писем — используйте get_emails для получения содержимого. Результаты включают queryState для инкрементальной синхронизации через get_search_updates.

Параметры:

• query (необязательно): Текстовый поиск по всем полям

• body (необязательно): Поиск только в теле сообщения

• from (необязательно): Фильтр по адресу отправителя

• to (необязательно): Фильтр по адресу получателя

• subject (необязательно): Фильтр по тексту темы

• inMailbox (необязательно): ID ящика для поиска (получите из get_mailboxes)

• hasKeyword (необязательно): Фильтр по ключевому слову (например, $seen, $flagged)

• notKeyword (необязательно): Исключение по ключевому слову (например, $seen, $draft)

• allInThreadHaveKeyword (необязательно): Все письма в цепочке должны иметь ключевое слово

• someInThreadHaveKeyword (необязательно): Хотя бы одно письмо в цепочке должно иметь ключевое слово

• before (необязательно): Только письма до даты (ISO 8601)

• after (необязательно): Только письма после даты (ISO 8601)

• limit (необязательно): Максимальное количество результатов (1-100, по умолчанию: 50)

• position (необязательно): Начальная позиция для пагинации (по умолчанию: 0)

get_emails

Получение конкретных писем по их ID. Используйте properties для запроса только необходимых данных — получение всех свойств возвращает большие объемы данных.

Параметры:

• ids: Массив ID писем (1-50 ID)

• properties (необязательно): Конкретные свойства для возврата. Рекомендуемые наборы:

  • Кратко: ["id", "subject", "from", "to", "receivedAt", "preview"]

  • Полное чтение: ["id", "subject", "from", "to", "cc", "receivedAt", "bodyValues", "textBody", "htmlBody"]

  • Примечание: Чтобы получить содержимое тела, включите bodyValues И textBody/htmlBody

get_threads

Получение цепочек писем по их ID. ID цепочек приходят из ответов get_emails (свойство threadId). Возвращает ID писем в цепочке — используйте get_emails для этих ID, чтобы получить содержимое.

Параметры:

• ids: Массив ID цепочек (1-20 ID)

get_email_changes

Получение ID писем, созданных, обновленных или удаленных с момента предыдущего состояния. Используйте строку state из ответа get_emails.

Параметры:

• sinceState: Строка состояния из предыдущего ответа get_emails

• maxChanges (необязательно): Максимальное количество изменений (1-500)

• fetchEmails (необязательно): Автоматическое получение полных деталей писем для измененных ID (по умолчанию: false)

• properties (необязательно): Свойства для получения, если fetchEmails равно true

get_search_updates

Получение изменений в рамках предыдущего поискового запроса с момента его queryState. Необходимо использовать те же параметры фильтра, что и в исходном вызове search_emails.

Параметры:

• sinceQueryState: queryState из предыдущего ответа search_emails

• Все параметры фильтра из search_emails (должны совпадать с исходным запросом)

• maxChanges (необязательно): Максимальное количество изменений (1-500)

mark_emails

Пометка писем как прочитанных/непрочитанных или отмеченных/снятых с флажка.

Параметры:

• ids: Массив ID писем (1-100 ID)

• seen (необязательно): Пометить как прочитанное (true) или непрочитанное (false)

• flagged (необязательно): Пометить как отмеченное (true) или снятое с флажка (false)

move_emails

Перемещение писем в другой ящик. Используйте get_mailboxes для поиска ID целевого ящика.

Параметры:

• ids: Массив ID писем (1-100 ID)

• mailboxId: ID целевого ящика (получите из get_mailboxes)

delete_emails

Окончательное удаление писем (нельзя отменить). Рекомендуется перемещение в корзину через move_emails для возможности восстановления.

Параметры:

• ids: Массив ID писем (1-100 ID)

send_email

Отправка нового письма. Требуется textBody или htmlBody (или оба).

Параметры:

• to: Массив получателей (name необязательно, email обязательно)

• cc (необязательно): Массив получателей копии

• bcc (необязательно): Массив получателей скрытой копии

• subject: Тема письма

• textBody (необязательно): Тело письма в обычном тексте

• htmlBody (необязательно): Тело письма в HTML

• identityId (необязательно): ID личности JMAP для отправки (используется значение по умолчанию сервера, если пропущено)

reply_to_email

Ответ на существующее письмо. Автоматически устанавливает To/CC, префикс темы Re: и заголовки цепочки (In-Reply-To, References).

Параметры:

• emailId: ID письма для ответа

• replyAll (необязательно): Включить всех исходных получателей (по умолчанию: false)

• subject (необязательно): Пользовательская тема ответа (по умолчанию Re: <оригинал>)

• textBody (необязательно): Тело письма в обычном тексте

• htmlBody (необязательно): Тело письма в HTML

• identityId (необязательно): ID личности JMAP для отправки (используется значение по умолчанию сервера, если пропущено)

Совместимость с JMAP-серверами

Этот сервер должен работать с любым почтовым сервером, поддерживающим JMAP, включая:

• Cyrus IMAP 3.0+

• Stalwart Mail Server

• FastMail (коммерческий)

• Apache James (с поддержкой JMAP)

Разработка

Запуск в режиме разработки

just watch          # Run with file watching
just start          # Run without watching

Тестирование

just test           # Run all tests
just check          # Format check + lint + type check
just fmt            # Auto-format code

Архитектура

Сервер построен с использованием:

• Deno: Современная среда выполнения JavaScript/TypeScript

• @modelcontextprotocol/sdk: Фреймворк MCP-сервера

• jmap-jam: Легковесный типизированный JMAP-клиент

• Zod: Проверка типов во время выполнения

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

• Все входные данные проверяются с помощью схем Zod

• Переменные окружения используются для конфиденциальной конфигурации

• Никакие секреты не логируются и не раскрываются в ответах

• Соблюдаются лучшие практики безопасности JMAP

Вклад в проект

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

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

3. Вносите изменения, следуя стилю функционального программирования

4. Тщательно протестируйте изменения

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

Лицензия

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

Связанные проекты

• jmap-jam — клиентская библиотека JMAP

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

• JMAP RFC 8620 — основной протокол JMAP

• JMAP RFC 8621 — JMAP для почты