Shared Timer

모두의 타이머를 Claude가 직접 만들고 제어할 수 있게 해주는 MCP 서버입니다.

Claude에게 이렇게 말하면 됩니다:

• "발표용 5분 타이머 만들어줘" → 뷰어 링크가 생김
• "타이머 시작해줘" / "1분 더 추가해줘" / "화면에 '곧 시작합니다' 띄워줘"
• "점심 메뉴 투표 열어줘. 짜장 vs 짬뽕" / "지금 몇 표야?" / "결과 공개해줘"
• "선착순 손들기 열어줘" / "퀴즈 내줘. 정답은 2번"

---

무엇을 할 수 있나 (도구 20개)

타이머 (14개)

도구	설명
create_timer	새 타이머 생성 + 관리자 화면 자동 팝업 (뷰어·컨트롤러 링크 발급)
open_controller / open_viewer	관리자 / 뷰어 화면을 이 PC 브라우저로 열기
get_timer_state	남은 시간·상태 읽기 (토큰 불필요)
start_timer / pause_timer / reset_timer	시작 / 일시정지 / 리셋
adjust_timer	남은 시간 ± 초 단위 조절
show_message / clear_message	화면에 문구 표시 / 지우기
schedule_start / cancel_scheduled_start	지정 시각 자동 시작 예약 / 취소
schedule_add / schedule_remove	예약 메시지 추가 / 제거 — 남은 시간이 N초가 되면 문구 자동 표시

투표·선착순 (6개) — 뷰어들이 폰으로 참여, 진행자가 집계를 봄

도구	설명
open_poll	선택 투표 열기 (질문 + 선택지 2~4개, 실시간 집계)
open_race	선착순 손들기 열기 (누른 순서대로 1~10등 명단)
open_quiz	선착순 퀴즈 열기 (정답을 빨리 누른 순서로 순위, 정답은 공개 전 은닉)
get_poll_results	실시간 집계·순위 읽기 (진행자용)
reveal_poll_results	뷰어에게 결과 공개/비공개 전환 (토글)
close_poll	종료하고 결과 고정

---

동작 원리 (한눈에)

• 타이머 생성은 HTTP(POST /create)로 합니다.
• 타이머 제어(시작·정지·리셋 등)는 실시간 소켓(socket.io)으로 합니다.

즉, 이미 있는 "모두의 타이머" 서버에 붙어서 명령을 전달하는 얇은 번역기입니다. 별도 서버 배포가 필요 없고, 각자 자기 PC에서 실행합니다.

---

설치

# 파이썬 3.10 이상 필요
pip install -r requirements.txt

Claude Desktop 에 연결하기

claude_desktop_config.json 파일의 mcpServers 안에 아래를 추가하세요. (/절대경로/ 부분은 이 파일이 있는 실제 경로로 바꾸세요.)

{
  "mcpServers": {
    "moduui-timer": {
      "command": "python",
      "args": ["/절대경로/timer_mcp.py"],
      "env": { "TIMER_BASE_URL": "https://shared-timer-d07t.onrender.com" }
    }
  }
}

설정 후 Claude Desktop 을 다시 시작하고 이렇게 말해보세요:

"발표용 3분 타이머 만들어줘"

---

⚠️ 알아두어야 할 점

• token 은 '제어 비밀번호'입니다. 타이머를 만들면 room_id 와 token 이 나오는데, 이 둘을 아는 사람은 그 타이머를 조종할 수 있습니다. 남에게는 뷰어 링크(viewer_url)만 주고, 컨트롤러 링크(토큰 포함)는 본인만 가지세요.
• 이 MCP 는 기본적으로 위 render 서버에 붙습니다. 자기만의 서버를 따로 운영한다면 TIMER_BASE_URL 환경변수를 그 주소로 바꾸면 됩니다.
• schedule_add 의 시간 형식 — "남은 시간(초)" 정수입니다(실서버 실측으로 확정). 예: 60 = 남은 시간이 1분이 되는 순간 문구가 표시됩니다. 시각 문자열("15:00")은 서버가 무시합니다. 특정 시각에 시작하려면 schedule_start(에폭 밀리초)를 쓰세요.
• 무료 호스팅 특성 — 타이머 서버는 render 무료 플랜이라 15분간 미사용 시 잠들며, 첫 요청이 50초쯤 걸릴 수 있습니다. 도구 호출이 timeout 나면 한 번 더 시도하세요.

---

라이선스

MIT License — 자유롭게 쓰고 고치고 공유할 수 있습니다. (LICENSE 파일 참고)