Journal Mandala MCP

Journal Mandala에 Claude로부터 직접 일기 항목을 작성하기 위한 MCP 서버입니다.

대화 도중 "생각의 흐름"을 만다라에 새기고 싶을 때 사용합니다.

필요한 것

• 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)을 편집합니다:

1계정 운영

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

2계정(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"
      }
    }
  }
}

각각 별도의 도구로 Claude에서 보입니다. "work에 기록해줘"와 같이 자연어로 전환 가능합니다.

설정 후 Claude Desktop을 재시작합니다.

API 키 발급

현재는 Journal Mandala 관리자(@takezone)에게 다음을 전달하여 발급받아야 합니다:

1. 본인의 Google 계정 이메일 주소

2. 라벨 이름 (예: alice-personal)

관리자로부터 API 키를 받으면, 위 설정의 JOURNAL_MANDALA_API_KEY에 복사하여 붙여넣습니다.

Note: 향후 브라우저에서 자동 발급할 예정입니다.

사용 방법

Claude와의 대화에서 "오늘 있었던 일을 일기에 기록해줘"와 같이 요청하면, add_journal_entry 도구가 호출되어 Journal Mandala에 항목이 추가됩니다.

제공 도구:

add_journal_entry — 일기 항목 추가

• title 제목 (생략 가능)

• event 사건 (무슨 일이 있었는지)

• thought 생각 (어떻게 느꼈는지)

• entry_date 날짜 YYYY-MM-DD (생략 시 JST 기준 오늘)

• entry_time 시간 HH:MM

• tags 태그 배열 — 문자열 배열로 전달할 것

  • ✅ 정답: ["업무", "운동"]

  • ❌ 오답: ["[\"업무\",\"운동\"]"] (JSON 문자열화된 배열을 1요소로 만들지 말 것)

• 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 — 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 키가 1회만 표시되므로 복사

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