Journal Mandala MCP

Это MCP-сервер для прямой записи дневниковых заметок в Journal Mandala из Claude.

Используется, когда вы хотите запечатлеть «поток мыслей» в мандале прямо во время разговора.

Что потребуется

• Node.js 20+

• Claude Desktop (или Claude Code)

• API-ключ Journal Mandala (инструкции по получению см. в разделе «Получение API-ключа»)

Related MCP server: Obsidian Nexus

Установка

Установите глобально через npm.

npm install -g --install-links github:takezone/journal-mandala-mcp

Флаг --install-links обязателен (без него создается символическая ссылка на временную директорию, и запуск станет невозможен).

Для обновления используйте ту же команду. Если вы ранее установили пакет без --install-links и он перестал работать:

npm uninstall -g journal-mandala-mcp
# 残骸掃除 (npm prefix は `npm prefix -g` で確認)
rm -rf $(npm prefix -g)/lib/node_modules/journal-mandala-mcp
rm -rf $(npm prefix -g)/lib/node_modules/.journal-mandala-mcp-*
npm install -g --install-links github:takezone/journal-mandala-mcp

Настройка Claude Desktop

Отредактируйте файл ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

Использование с 1 аккаунтом

{
  "mcpServers": {
    "journal-mandala": {
      "command": "journal-mandala-mcp",
      "env": {
        "JOURNAL_MANDALA_API_KEY": "jm_XXXXXXXXXXXXXXXXXXXXXXXX"
      }
    }
  }
}

Использование с 2 аккаунтами (личный / рабочий)

{
  "mcpServers": {
    "journal-mandala-personal": {
      "command": "journal-mandala-mcp",
      "env": {
        "JOURNAL_MANDALA_API_KEY": "jm_PERSONAL_KEY"
      }
    },
    "journal-mandala-work": {
      "command": "journal-mandala-mcp",
      "env": {
        "JOURNAL_MANDALA_API_KEY": "jm_WORK_KEY"
      }
    }
  }
}

Каждый из них будет виден в Claude как отдельный инструмент. Переключаться можно естественным языком, например: «запиши в work».

После настройки перезапустите Claude Desktop.

Получение API-ключа

На данный момент для получения ключа необходимо сообщить администратору Journal Mandala (@takezone) следующее:

1. Адрес электронной почты вашего аккаунта Google

2. Название метки (например, alice-personal)

Как только администратор пришлет API-ключ, вставьте его в поле JOURNAL_MANDALA_API_KEY в настройках выше.

Примечание: В будущем планируется автоматическая выдача ключей через браузер.

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

В разговоре с Claude попросите, например, «запиши сегодняшние события в дневник», после чего будет вызван инструмент add_journal_entry и запись будет добавлена в Journal Mandala.

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

add_journal_entry — добавление записи в дневник

• title Заголовок (необязательно)

• event Событие (что произошло)

• thought Мысли (что вы почувствовали)

• entry_date Дата YYYY-MM-DD (по умолчанию — сегодня по JST)

• entry_time Время HH:MM

• tags Массив тегов — передавать как массив строк

  • ✅ Правильно: ["работа", "спорт"]

  • ❌ Неправильно: ["[\"работа\",\"спорт\"]"] (не делайте массив JSON-строкой внутри одного элемента)

• star_rating Оценка от 1 до 5

find_entries — список недавних записей

Используется для получения ID. Возвращает записи в порядке убывания даты обновления.

• limit Количество записей (по умолчанию 20, максимум 100)

update_entry — обновление существующей записи

Частичное обновление по ID. Перезаписываются только указанные поля, пропущенные поля сохраняются.

• id Обязательно

• Остальные поля аналогичны add_journal_entry / add_todo и являются необязательными

Как использовать: узнайте ID через find_entries → обновите через update_entry

add_todo — добавление задачи (Todo)

• title Название задачи (обязательно)

• thought Заметка о задаче (необязательно)

• entry_date Дата создания (по умолчанию — сегодня по JST)

• due_date Срок выполнения YYYY-MM-DD (необязательно)

• todo_status pending | in_progress | completed | cancelled (по умолчанию pending)

• todo_points Оценочные баллы (необязательно)

• is_today Флаг списка дел на сегодня (необязательно)

• tags Массив тегов

  • 1: Неприятное/негативное событие

  • 2: Обычный день (по умолчанию)

  • 3: День, когда произошло что-то хорошее

  • 4: День, когда произошло что-то очень хорошее

  • 5: Событие уровня «главное событие жизни»

  • Не ставьте 5 без веской причины. Базовое значение — 2, если произошло что-то хорошее — 3 или 4

Одно из полей title / event / thought обязательно для заполнения.

Дополнительные переменные окружения

• JOURNAL_MANDALA_API_URL — API-эндпоинт (по умолчанию: https://journal-mandala.vercel.app)

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

• Инструменты не отображаются в Claude → Возможна синтаксическая ошибка JSON в файле конфигурации. Проверьте логи MCP в меню Developer в Claude Desktop

• Ошибка API 401 → JOURNAL_MANDALA_API_KEY недействителен. Запросите повторную выдачу у администратора

• Сетевая ошибка → Проверьте статус работы Vercel

Для администраторов: управление и восстановление API-ключей

Справочная информация на случай, если пользователь потерял ключ. Этот MCP обращается к оригиналу, хранящемуся на стороне Vercel, поэтому даже если копия ~/.claude.json будет удалена, доступ можно восстановить.

Трехуровневая структура

При аутентификации API проверка идет в порядке: KV → env var.

Процедура восстановления (для владельца проекта)

В директории проекта (основной journal-mandala):

# Vercel プロジェクトと連携（初回のみ）
vercel link --yes --project journal-mandala

# サーバー環境変数をローカルに取得
vercel env pull .env.vercel

# env var 内のキー確認
grep JM_API_ACCOUNTS .env.vercel

# KV 内のキー一覧スキャン
source .env.vercel
curl -s "${KV_REST_API_URL}/scan/0/match/jm:account:*/count/100" \
  -H "Authorization: Bearer ${KV_REST_API_TOKEN}"

# 特定アカウントの中身を見る
curl -s "${KV_REST_API_URL}/get/jm:account:jm_XXXXX" \
  -H "Authorization: Bearer ${KV_REST_API_TOKEN}"

# 終わったら機密情報を必ず削除
rm -f .env.vercel .vercel/project.json && rmdir .vercel 2>/dev/null

Выпуск нового ключа

1. Войдите в нужный аккаунт Google в Chrome

2. Откройте https://journal-mandala.vercel.app/api/enroll?label=<любая метка>

3. После OAuth-авторизации API-ключ отобразится на экране один раз — скопируйте его

4. Обновите mcpServers.*.env.JOURNAL_MANDALA_API_KEY в ~/.claude.json

При повторной регистрации (enroll) с тем же аккаунтом Google старый ключ автоматически аннулируется и заменяется новым.

Настройка на другом Mac (втором и последующих)

Поскольку API-ключ привязан к аккаунту Google, при смене устройства можно использовать тот же ключ (повторная регистрация не требуется).

# 1. (未インストールなら) Node.js をインストール
brew install node

# 2. MCPサーバーをグローバルインストール
npm install -g --install-links github:takezone/journal-mandala-mcp

# 3. ~/.claude.json に mcpServers を追記（既存設定を壊さないよう python でマージ推奨）
python3 - <<'PY'
import json, os
p = os.path.expanduser('~/.claude.json')
with open(p) as f: c = json.load(f)
c.setdefault('mcpServers', {})
c['mcpServers'].update({
    'journal-mandala-personal': {
        'command': 'journal-mandala-mcp',
        'env': {'JOURNAL_MANDALA_API_KEY': 'jm_XXXXX'}  # ←実キー
    },
    'journal-mandala-work': {
        'command': 'journal-mandala-mcp',
        'env': {'JOURNAL_MANDALA_API_KEY': 'jm_YYYYY'}  # ←実キー
    },
})
with open(p, 'w') as f: json.dump(c, f, indent=2, ensure_ascii=False)
print('updated')
PY

# 4. Claude Code を再起動（/exit → claude 再実行）

Если существующего ключа нет под рукой: скопируйте его из ~/.claude.json на домашнем Mac или получите его из Vercel с помощью «Процедуры восстановления» выше.

Рекомендация по распределенному использованию: Если использовать разные ключи на домашнем и рабочем Mac (например, ?label=personal-home / ?label=personal-work), то в случае утечки одного ключа другой не пострадает, а ротацию можно проводить по отдельности. Использование одного ключа удобнее, но выбор зависит от ваших предпочтений.

Лицензия

MIT