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~/Library/Application Support/Claude/claude_desktop_config.json (macOS)을 편집합니다:
{
"mcpServers": {
"journal-mandala": {
"command": "journal-mandala-mcp",
"env": {
"JOURNAL_MANDALA_API_KEY": "jm_XXXXXXXXXXXXXXXXXXXXXXXX"
}
}
}
}{
"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을 재시작합니다.
현재는 Journal Mandala 관리자(@takezone)에게 다음을 전달하여 발급받아야 합니다:
본인의 Google 계정 이메일 주소
라벨 이름 (예: 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 가동 상태 확인
운영자가 키를 분실했을 때의 참고 사항입니다. 이 MCP는 Vercel 측에 저장된 원본을 참조하므로 ~/.claude.json 사본이 사라져도 복구할 수 있습니다.
계층 | 위치 | 역할 |
서버 env var | Vercel | 초기 seed 정적 계정 배열 (원본) |
서버 KV | Vercel KV (Upstash Redis) |
|
클라이언트 |
| 인증용 키 사본 (분실 시 재발급 가능) |
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/nullChrome에서 대상 Google 계정으로 로그인
https://journal-mandala.vercel.app/api/enroll?label=<임의 라벨> 접속
OAuth 승인 → 화면에 API 키가 1회만 표시되므로 복사
~/.claude.json의 mcpServers.*.env.JOURNAL_MANDALA_API_KEY에 반영
같은 Google 계정으로 재enroll하면 기존 키는 자동 만료되고 새 키로 교체됩니다.
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
Journal Mandala に新しい日記エントリを作成する。event (出来事: 何があったか) と thought (思考: それについてどう感じたか) は両方とも任意だが、少なくとも title/event/thought のいずれかは必須。日付を省略すると日本時間での今日の日付になる。
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | エントリのタイトル（任意。省略時は先頭20文字から自動生成） | |
| event | No | 出来事: 何があったかを事実ベースで記述 | |
| thought | No | 思考: それについてどう感じたか・何を考えたか | |
| entry_date | No | YYYY-MM-DD 形式。省略時は日本時間での今日 | |
| entry_time | No | HH:MM 形式（任意） | |
| tags | No | タグの配列（任意） | |
| star_rating | No | 1-5 の評価（任意） |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It describes key behaviors: the tool creates a new entry (implying a write/mutation operation), specifies default values for title (auto-generated from first 20 characters) and date (today's Japan time), and mentions the requirement for at least one of title/event/thought. However, it lacks details on permissions, error handling, or response format, leaving gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately concise with two sentences that efficiently convey the tool's purpose and key constraints. It is front-loaded with the main action and avoids unnecessary details, though it could be slightly more structured by separating usage rules into bullet points for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, mutation operation) and lack of annotations and output schema, the description is moderately complete. It covers the creation action, parameter requirements, and defaults, but misses details on permissions, error cases, and what the tool returns, which are important for a write tool with no structured output information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, providing detailed descriptions for all 7 parameters. The description adds minimal value beyond the schema by mentioning that event and thought are optional but at least one of title/event/thought is required, and that the date defaults to today's Japan time if omitted. This aligns with the baseline of 3 when the schema does most of the work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Journal Mandala に新しい日記エントリを作成する' (creates a new journal entry in Journal Mandala). It specifies the verb (create/作成する) and resource (journal entry/日記エントリ). However, since there are no sibling tools mentioned, it cannot demonstrate differentiation from alternatives, preventing a score of 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides implied usage guidance by stating that at least one of title/event/thought is required, and that the date defaults to today's date in Japan time if omitted. However, it lacks explicit guidance on when to use this tool versus alternatives (none mentioned) or any prerequisites or exclusions, keeping it at a basic level.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0add_journal_entryScored across 1 tool
With only one tool, there is no possibility of ambiguity or overlap between tools. The tool's purpose is clearly defined as adding journal entries, and no other tools exist to cause confusion.
A single tool inherently has perfect naming consistency, as there are no other tools to compare it against. The name 'add_journal_entry' follows a clear verb_noun pattern (add + journal_entry).
A single tool for a journaling server is too few for the apparent scope. Journaling typically involves operations like viewing, updating, deleting, or searching entries, but this server only supports adding entries, which severely limits functionality.
The tool surface is severely incomplete for a journaling domain. It only allows adding entries, with no tools for retrieving, updating, deleting, or searching entries. This creates dead ends for agents, as they cannot perform basic CRUD operations beyond creation.
Plan trips directly into TravelOwl from a conversation with Claude.
First strength app Claude can write to: plan training in chat, it lands in the app ready to log.
Notes and actions in one app. Let Claude or ChatGPT read and update them.
Handwritten iPad journal your AI can read and write tasks back to, over MCP.