Journal Mandala MCP

Este es un servidor MCP para escribir entradas de diario directamente en Journal Mandala desde Claude.

Se utiliza cuando deseas grabar el "flujo de pensamiento" en el mandala durante una conversación.

Requisitos

• Node.js 20+

• Claude Desktop (o Claude Code)

• Clave API de Journal Mandala (consulta "Obtención de la clave API" para saber cómo generarla)

Related MCP server: Obsidian Nexus

Instalación

Instálalo globalmente con npm.

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

--install-links es obligatorio (si no se incluye, se creará un enlace simbólico a un directorio temporal y no se podrá iniciar).

Ejecuta el mismo comando para actualizar. Si anteriormente lo instalaste sin --install-links y está dañado:

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

Configuración de Claude Desktop

Edita ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

Uso con 1 cuenta

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

Si deseas alternar entre 2 cuentas (personal / trabajo)

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

Cada una aparecerá como una herramienta distinta en Claude. Puedes alternar usando lenguaje natural, como "registra esto en el trabajo".

Reinicia Claude Desktop después de configurar.

Obtención de la clave API

Actualmente, debes solicitarla al administrador de Journal Mandala (@takezone) proporcionando lo siguiente:

1. Tu dirección de correo electrónico de la cuenta de Google

2. Un nombre de etiqueta (ej: alice-personal)

Una vez que el administrador te envíe la clave API, pégala en JOURNAL_MANDALA_API_KEY en la configuración anterior.

Nota: Está previsto que en el futuro se pueda generar automáticamente desde el navegador.

Uso

Si le pides a Claude durante una conversación "registra los eventos de hoy en el diario", se llamará a la herramienta add_journal_entry y se añadirá la entrada a Journal Mandala.

Herramientas disponibles:

add_journal_entry — Añadir entrada de diario

• title Título (opcional)

• event Evento (qué sucedió)

• thought Pensamiento (cómo te sentiste)

• entry_date Fecha YYYY-MM-DD (por defecto, hoy en JST)

• entry_time Hora HH:MM

• tags Array de etiquetas — Debe pasarse como un array de cadenas

  • ✅ Correcto: ["trabajo", "ejercicio"]

  • ❌ Incorrecto: ["[\"trabajo\",\"ejercicio\"]"] (no conviertas el array en una cadena JSON como un solo elemento)

• star_rating Valoración de 1 a 5

find_entries — Lista de entradas recientes

Se usa para obtener el ID. Devuelve las entradas ordenadas por fecha de actualización reciente.

• limit Número de resultados (por defecto 20, máximo 100)

update_entry — Actualizar entrada existente

Actualización parcial especificando el ID. Solo se sobrescriben los campos especificados; los campos omitidos se mantienen.

• id Obligatorio

• Los demás campos son opcionales y coinciden con add_journal_entry / add_todo

Uso: busca el ID con find_entries → actualiza con update_entry

add_todo — Añadir tarea (Todo)

• title Nombre de la tarea (obligatorio)

• thought Nota sobre la tarea (opcional)

• entry_date Fecha de creación (por defecto, hoy en JST)

• due_date Fecha de vencimiento YYYY-MM-DD (opcional)

• todo_status pending | in_progress | completed | cancelled (por defecto, pending)

• todo_points Puntos estimados (opcional)

• is_today Flag para la lista de hoy (opcional)

• tags Array de etiquetas

  • 1: Evento sutil o negativo

  • 2: Un día normal (por defecto)

  • 3: Un día con algo bastante bueno

  • 4: Un día con algo muy bueno

  • 5: Evento importante en la vida

  • No asignes 5 a la ligera. Por defecto es 2; usa 3 o 4 si ocurre algo bueno

Es obligatorio incluir al menos uno de los siguientes: title / event / thought.

Variables de entorno opcionales

• JOURNAL_MANDALA_API_URL — Endpoint de la API (por defecto: https://journal-mandala.vercel.app)

Solución de problemas

• La herramienta no aparece en Claude → Posible error de sintaxis JSON en el archivo de configuración. Revisa los registros de MCP en el menú de desarrollador de Claude Desktop.

• Error de API 401 → JOURNAL_MANDALA_API_KEY no es válida. Solicita una nueva al administrador.

• Error de red → Verifica el estado de funcionamiento de Vercel.

Para administradores: Gestión y recuperación de claves API

Referencia para cuando un usuario pierde su clave. Este MCP hace referencia al registro maestro guardado en Vercel, por lo que se puede recuperar incluso si se pierde la copia de ~/.claude.json.

Estructura de 3 capas

Durante la autenticación de la API, se verifica primero en KV y luego en env var.

Procedimiento de recuperación (propietario del proyecto)

En el directorio del proyecto (el núcleo de 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

Emisión de nueva clave

1. Inicia sesión con la cuenta de Google correspondiente en Chrome.

2. Abre https://journal-mandala.vercel.app/api/enroll?label=<etiqueta_arbitraria>.

3. Autorización OAuth → La clave API se mostrará una sola vez en pantalla, cópiala.

4. Actualiza mcpServers.*.env.JOURNAL_MANDALA_API_KEY en ~/.claude.json.

Si vuelves a realizar el proceso de inscripción con la misma cuenta de Google, la clave anterior se revocará automáticamente y se reemplazará por la nueva.

Configuración en otro Mac (segundo equipo o más)

Como la clave API está vinculada a la cuenta de Google, puedes usar la misma clave aunque cambies de máquina (no es necesario volver a inscribirse).

# 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 再実行）

Si no tienes la clave existente a mano: Cópiala desde ~/.claude.json de tu otro Mac o recupérala desde Vercel siguiendo el "Procedimiento de recuperación" anterior.

Recomendación de uso distribuido: Si usas claves distintas en el Mac de casa y el del trabajo (ej: ?label=personal-home / ?label=personal-work), si una se filtra, la otra no se verá afectada y la rotación se puede hacer por separado. Aunque es más cómodo usar la misma clave, puedes elegir según tu preferencia.

Licencia

MIT