Journal Mandala MCP

这是一个用于从 Claude 直接向 Journal Mandala 写入日记条目的 MCP 服务器。

当你希望在对话过程中将“思维流”记录到 Mandala 时使用。

必要条件

• Node.js 20+

• Claude Desktop (或 Claude Code)

• Journal Mandala 的 API 密钥（获取方法请参考“获取 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)：

单账号运行

{
  "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 中它们会显示为不同的工具。可以通过自然语言切换，例如“记录到工作”。

配置完成后请重启 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 的所有字段均可任意指定

使用方法：通过 find_entries 查询 ID → 使用 update_entry 更新

add_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 语法错误。请在 Claude Desktop 的 Developer 菜单中查看 MCP 日志

• API 错误 401 → JOURNAL_MANDALA_API_KEY 无效。请请求管理员重新签发

• 网络错误 → 请检查 Vercel 的运行状态

管理员指南：API 密钥的管理与恢复

供运营者在丢失密钥时参考。由于此 MCP 引用的是保存在 Vercel 侧的正本，即使 ~/.claude.json 的副本丢失也可以恢复。

3 层结构

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. 在 Chrome 中登录目标 Google 账号

2. 打开 https://journal-mandala.vercel.app/api/enroll?label=<任意标签>

3. OAuth 授权 → 屏幕上会显示一次 API 密钥，请复制

4. 反映到 ~/.claude.json 的 mcpServers.*.env.JOURNAL_MANDALA_API_KEY 中

使用同一个 Google 账号重新 enroll 时，旧密钥会自动失效并替换为新密钥。

在其他 Mac（第 2 台及以后）上进行设置

由于 API 密钥与 Google 账号绑定，即使更换机器也可以使用相同的密钥（无需重新 enroll）。

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

如果手头没有现有密钥： 请从家里 Mac 的 ~/.claude.json 中复制，或者通过上述“恢复步骤”从 Vercel 获取。

推荐分布式运营： 如果在家里 Mac 和公司 Mac 上使用不同的密钥（例如：?label=personal-home / ?label=personal-work），即使其中一个泄露也不会影响另一个，且轮换时只需分别处理。虽然使用同一个密钥更方便，但可以根据喜好选择。

许可证

MIT