sonsuchup-mcp

손수첩(Sonsuchup) — 추리·사건 정리용 개인 웹 도구를 Claude Desktop, Cursor 등 MCP 클라이언트에 연결하는 stdio 서버. Sonsuchup MCP server — Stdio bridge that lets Claude Desktop, Cursor, and other MCP clients read and write your case-investigation data on https://sonsuchup.com.

🇰🇷 한국어

손수첩이 뭔가요?

손수첩은 추리소설·미스터리·실제 사건을 정리하기 위한 개인 웹 도구입니다. 사건 개요, 인물관계도, 알리바이, 타임라인, 기록을 한 곳에서 다룰 수 있습니다. 이 MCP 서버는 그 데이터를 AI 도구로도 다룰 수 있게 해 줍니다.

시작하기 (30초)

1. 토큰 발급

손수첩 웹 → 회원가입/로그인 → 우측 상단 ⚙ 설정 → MCP 연결 → 새 토큰 발급. 평문 토큰(sonsu_mcp_...)은 발급 직후 한 번만 표시되니 즉시 복사하세요.

2. Claude Desktop에 등록

Claude Desktop 메뉴 → Settings → Developer → Edit Config 클릭. 열린 claude_desktop_config.json에 아래를 추가:

{
  "mcpServers": {
    "sonsuchup": {
      "command": "npx",
      "args": ["-y", "sonsuchup-mcp"],
      "env": {
        "SONSUCHUP_TOKEN": "여기에-발급한-sonsu_mcp_xxx-붙여넣기"
      }
    }
  }
}

저장 후 Claude Desktop 완전 종료(Cmd+Q) → 재실행.

3. 사용

새 채팅에서:

sonsuchup MCP로 내 사건 목록 보여줘
"월광 호텔 401호 살인 사건"의 알리바이 모순을 찾아줘
"테스트 사건"을 만들고 인물 두 명을 추가해줘

4. 여러 계정 연결 (선택)

계정을 여러 개 쓴다면 env에 SONSUCHUP_TOKEN_2, SONSUCHUP_TOKEN_3 … 을 추가하세요. 각 토큰은 해당 계정으로 손수첩에 로그인한 상태에서 따로 발급해야 합니다.

{
  "mcpServers": {
    "sonsuchup": {
      "command": "npx",
      "args": ["-y", "sonsuchup-mcp"],
      "env": {
        "SONSUCHUP_TOKEN": "sonsu_mcp_개인계정-토큰",
        "SONSUCHUP_TOKEN_2": "sonsu_mcp_관리계정-토큰"
      }
    }
  }
}

연결 후 대화에서:

지금 어느 손수첩 계정에 연결돼 있어?       (→ whoami)
연결된 손수첩 계정 목록 보여줘             (→ list_accounts)
admin@example.com 계정으로 전환해줘        (→ use_account)

SONSUCHUP_TOKEN이 기본(활성) 계정이며 use_account로 전환합니다. 활성 계정은 메모리에만 유지되어 Claude Desktop을 재시작하면 다시 기본 계정으로 돌아갑니다.

제공 도구 (13개)

계정

사건

모든 응답에 손수첩 웹의 직접 링크(url)가 포함됩니다 — Claude가 답변에 클릭 가능한 링크로 인용합니다.

환경 변수

보안

• 토큰 평문은 발급 직후 1회만 표시됩니다. DB엔 sha256 해시만 저장됩니다.

• 분실 시 손수첩 웹에서 폐기 → 재발급 하세요.

• 패키지 안의 Supabase anon key는 공개돼도 안전합니다 (Row Level Security + MCP 토큰 검증으로 보호).

• 토큰은 자신의 사건만 접근할 수 있습니다 (RLS).

문제 해결

Server disconnected / Could not attach to MCP server

• 설정에서 command가 npx가 아니라 node로 잘못 들어갔는데 args에 스크립트 경로가 빠진 경우 자주 발생. npx 사용을 권장.

• 또는 Claude Desktop을 창만 닫지 말고 Cmd+Q로 완전 종료 후 재실행.

MCP 토큰이 유효하지 않거나 폐기되었습니다

• 손수첩 웹에서 새 토큰을 발급하고 config의 SONSUCHUP_TOKEN을 교체. Claude Desktop 재시작.

도구가 안 보임 / 채팅이 커넥터 검색만 시도함

• Claude Desktop의 Settings → Developer → Local MCP Servers 화면에서 sonsuchup 상태가 running인지 확인.

• failed면 "로그 보기" 또는 tail ~/Library/Logs/Claude/mcp-server-sonsuchup.log로 원인 확인.

nvm 등으로 node 경로가 비표준일 때

• npx로 실행하면 일반적으로 PATH 문제 없음. node 절대경로 방식이 필요하면 which node 결과를 command 값으로 사용.

로컬 개발

git clone https://github.com/dalboki/sonsuchup-mcp.git
cd sonsuchup-mcp
npm install
npm run build
SONSUCHUP_TOKEN=... node dist/index.js   # stdio 대기 상태면 정상 (Ctrl+C 종료)

Claude Desktop에서 publish 전 버전 테스트하려면:

{
  "mcpServers": {
    "sonsuchup": {
      "command": "node",
      "args": ["/절대/경로/sonsuchup-mcp/dist/index.js"],
      "env": { "SONSUCHUP_TOKEN": "..." }
    }
  }
}

🇺🇸 English

What is Sonsuchup?

Sonsuchup (손수첩, "hand notebook") is a personal web tool for organizing detective fiction, mysteries, and real-life cases — overview, people graph, alibis, timeline, and field notes in one place. This MCP server exposes that data to AI assistants.

Quick start

1. Issue a token

On sonsuchup.com, sign up / log in → ⚙ Settings → MCP 연결 → 새 토큰 발급. The plaintext token (sonsu_mcp_...) is shown once — copy it immediately.

2. Register with Claude Desktop

Claude Desktop → Settings → Developer → Edit Config → add:

{
  "mcpServers": {
    "sonsuchup": {
      "command": "npx",
      "args": ["-y", "sonsuchup-mcp"],
      "env": {
        "SONSUCHUP_TOKEN": "paste-your-sonsu_mcp_xxx-here"
      }
    }
  }
}

Save and fully quit Claude Desktop (Cmd+Q), then reopen.

3. Use it

In a new chat:

Show my Sonsuchup cases via MCP
Find alibi contradictions in the "Moonlight Hotel Room 401" murder case
Create a test case and add two people to it

4. Connect multiple accounts (optional)

To use more than one account, add SONSUCHUP_TOKEN_2, SONSUCHUP_TOKEN_3 … to env. Each token must be issued while logged into that account on the Sonsuchup web app.

{
  "mcpServers": {
    "sonsuchup": {
      "command": "npx",
      "args": ["-y", "sonsuchup-mcp"],
      "env": {
        "SONSUCHUP_TOKEN": "sonsu_mcp_personal-account-token",
        "SONSUCHUP_TOKEN_2": "sonsu_mcp_admin-account-token"
      }
    }
  }
}

Then, in chat:

Which Sonsuchup account am I connected to?   (→ whoami)
List my connected Sonsuchup accounts          (→ list_accounts)
Switch to admin@example.com                   (→ use_account)

SONSUCHUP_TOKEN is the default (active) account; use_account switches it. The active account lives in memory only and resets to the default when Claude Desktop restarts.

Tools (13)

Accounts

Cases

Every response includes a url to the case page in the Sonsuchup web app so the model can cite a clickable link.

Environment variables

Security model

• Plaintext token is shown once at issue time. Only a sha256 hash is stored server-side.

• Lost a token? Revoke it on the web and issue a new one.

• The embedded Supabase anon key is safe to publish — protected by Postgres RLS and MCP token verification.

• A token can only access its owner's cases (enforced by RLS).

Local development

git clone https://github.com/dalboki/sonsuchup-mcp.git
cd sonsuchup-mcp
npm install
npm run build
SONSUCHUP_TOKEN=... node dist/index.js   # Stdio waiting = healthy (Ctrl+C to exit)

To test a pre-publish build in Claude Desktop, point command to node and args to the absolute path of dist/index.js.

License

MIT © dalboki