Journal Mandala MCP

This is an MCP server for writing journal entries directly to Journal Mandala from Claude.

Use this when you want to carve your "stream of thought" into your Mandala during a conversation.

Requirements

• Node.js 20+

• Claude Desktop (or Claude Code)

• Journal Mandala API Key (See "Obtaining an API Key" for how to issue one)

Related MCP server: Obsidian Nexus

Installation

Install globally via npm.

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

--install-links is mandatory (without it, it creates a symlink to a temporary directory, preventing it from launching).

Run the same command again to update. If you previously installed it without --install-links and it is broken:

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 Configuration

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

Single Account Setup

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

Switching Between Two Accounts (personal / work)

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

Each will appear as a separate tool in Claude. You can switch between them using natural language, such as "Record this to work."

Restart Claude Desktop after configuring.

Obtaining an API Key

Currently, please contact the Journal Mandala administrator (@takezone) with the following information to have one issued:

1. Your Google account email address

2. A label name (e.g., alice-personal)

Once the administrator sends you the API key, copy and paste it into JOURNAL_MANDALA_API_KEY in the configuration above.

Note: We plan to enable automatic issuance via the browser in the future.

Usage

When you ask Claude something like "Record today's events in my journal" during a conversation, the add_journal_entry tool will be called to add an entry to Journal Mandala.

Provided tools:

add_journal_entry — Add a journal entry

• title Title (optional)

• event Event (what happened)

• thought Thought (how you felt)

• entry_date Date YYYY-MM-DD (defaults to today in JST)

• entry_time Time HH:MM

• tags Array of tags — Must be passed as an array of strings

  • ✅ Correct: ["Work", "Exercise"]

  • ❌ Incorrect: ["[\"Work\",\"Exercise\"]"] (Do not make a JSON-stringified array a single element)

• star_rating 1-5 rating

find_entries — List recent entries

Used to retrieve IDs. Returns entries in order of most recent update.

• limit Number of items to retrieve (default 20, max 100)

update_entry — Update an existing entry

Partial update by specifying an ID. Only specified fields are overwritten; omitted fields are maintained.

• id Required

• All other fields are the same as add_journal_entry / add_todo and are optional

Usage: Find the ID with find_entries → Update with update_entry

add_todo — Add a Todo

• title Task name (Required)

• thought Note about the task (optional)

• entry_date Creation date (defaults to today in JST)

• due_date Due date YYYY-MM-DD (optional)

• todo_status pending | in_progress | completed | cancelled (defaults to pending)

• todo_points Estimated points (optional)

• is_today Flag for "today's list" (optional)

• tags Array of tags

  • 1: Subtle/negative event

  • 2: Normal day (default)

  • 3: Day with some good things

  • 4: Day with quite good things

  • 5: Major life event level

  • Do not assign 5 lightly. Default to 2; use 3 or 4 if something good happens.

At least one of title / event / thought is required.

Optional Environment Variables

• JOURNAL_MANDALA_API_URL — API endpoint (default: https://journal-mandala.vercel.app)

Troubleshooting

• Tool not appearing in Claude → Possible JSON syntax error in the config file. Check the MCP logs in the Claude Desktop Developer menu.

• API Error 401 → JOURNAL_MANDALA_API_KEY is invalid. Request a reissue from the administrator.

• Network Error → Check the Vercel status.

For Administrators: API Key Management and Recovery

Reference for when a user loses their key. This MCP references the master record stored on the Vercel side, so it can be recovered even if the copy of ~/.claude.json is lost.

3-Layer Structure

During API authentication, it checks KV first, then the env var.

Recovery Procedure (Project Owner)

In the project directory (the journal-mandala root):

# 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

Issuing a New Key

1. Log in with the target Google account in Chrome.

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

3. OAuth approval → The API key will be displayed only once on the screen; copy it.

4. Update mcpServers.*.env.JOURNAL_MANDALA_API_KEY in ~/.claude.json.

Re-enrolling with the same Google account will automatically revoke the old key and replace it with a new one.

Setting up on another Mac (2nd machine onwards)

Since the API key is tied to the Google account, the same key can be used even if the machine changes (no re-enrollment required).

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

If you don't have the existing key on hand: Copy it from ~/.claude.json on your primary Mac, or retrieve it from Vercel using the "Recovery Procedure" above.

Recommendation for distributed use: If you use different keys for your home Mac and work Mac (e.g., ?label=personal-home / ?label=personal-work), a leak in one won't affect the other, and rotation can be done separately. While using the same key is more convenient, choose based on your preference.

License

MIT