26. MCP Zapier 툴 레퍼런스 (실전)¶

Claude Code CLI에 연결된 Zapier/Notion MCP를 실제로 쓸 때 필요한 실전 노하우 모음. 개념 설명은 04-mcp.md, 연결 상태 스냅샷은 ~/.claude/memory/mcp_tools_available.md 참고.

핵심 개념 요약¶

Zapier MCP는 Zapier 서버를 경유해서 Claude Code가 Gmail/Google Workspace/Make 등을 조작하게 해줌. 장점은 한 번 OAuth 연결하면 Google Docs 편집/Gmail 발송/Calendar 수정이 전부 가능한 것. 단점은 호출 1회당 2 Zapier tasks 소모 → 무료 100/월 한도에 빠르게 도달.

Notion MCP는 Anthropic 공식 커넥터라 별도 API 한도 없음 (Notion 자체 rate limit만).

툴 호출 2단계 패턴¶

1단계: 스키마 로드¶

새 세션에서는 툴 이름만 노출되고 파라미터 스키마가 숨어있음 → ToolSearch로 로드:

ToolSearch(query="select:mcp__claude_ai_Zapier__google_docs_find_and_replace_text,mcp__claude_ai_Notion__notion-fetch")

여러 툴을 한 번에 로드하면 효율적.

2단계: 실제 호출¶

스키마 로드 후에는 일반 툴처럼 사용.

Google Docs: 실전 사용 예시¶

문서 전체 읽기¶

google_docs_get_document_content(
  document_id = "1N1WkFgJ...",
  instructions = "Return complete body text",
  output_hint = "Full raw document body text for verification"
)

주의: 긴 문서는 결과가 토큰 제한 넘어서 파일로 저장될 수 있음. instructions에서 범위를 좁히거나, 반환 후 Python으로 후처리.

찾아 바꾸기¶

google_docs_find_and_replace_text(
  document_id = "1N1WkFgJ...",
  find_text = "30기",
  replace_text = "31기",
  match_case = true,
  instructions = "기수 이름 전역 교체",
  output_hint = "total number of replacements"
)

결과 필드: 응답 results 필드에 치환된 건수가 숫자로 들어옴. 단 Zapier의 output_hint 해석에 따라 간혹 .results | length(=1)로만 나와 실제 건수가 안 보일 수 있음 → 명확한 output_hint로 해결.

주의사항¶

하이퍼링크 URL 교체 어려움: find_and_replace_text는 표시 텍스트만 바꿈. 클릭 시 이동하는 URL은 그대로. 실제 URL을 바꾸려면 Docs UI에서 수동 편집하거나 hyperlink 블록 전체를 교체
줌 링크 같은 외부 URL: 그대로 유지됨. 새 미팅 링크로 바꿔야 한다면 수동 교체 필요
빈 문자열 replace: replace_text = "" 로 링크 삭제 가능 (2026-04-24 위너책쓰기 세션에서 YouTube 링크 2종 제거할 때 사용)

Notion: 실전 사용 예시¶

페이지/DB fetch¶

notion-fetch(id = "https://www.notion.so/...")

- URL 그대로 넣어도 됨. UUID도 됨. - DB를 fetch하면 데이터소스 ID도 함께 반환됨. - 주의 (민티 글로벌 CLAUDE.md): data_source_id 직접 fetch 시 404 → DB URL로 먼저 fetch해야 함.

페이지 내용 수정 (update_content)¶

가장 많이 쓰는 패턴.

notion-update-page(
  page_id = "34c9b94aaba680d2abedcad8816867b6",
  command = "update_content",
  properties = {},
  content_updates = [
    {"old_str": "원본 텍스트", "new_str": "바꿀 텍스트"},
    {"old_str": "다른 블록", "new_str": "새 내용"}
  ]
)

old_str은 현재 페이지 본문과 정확히 매칭되어야 함 (Enhanced Markdown 형식 그대로)
한 번에 최대 100개 쌍 전달 가능
매칭 실패해도 에러는 안 나고 조용히 skip. → 업데이트 후 반드시 notion-fetch로 검증
properties가 스키마상 required지만 {} (빈 객체) 넘겨도 됨

Enhanced Markdown Escape 규칙¶

Notion 본문은 Enhanced Markdown으로 직렬화되어 저장됨. 다음 문자가 escape됨:

원본 문자	Notion 저장 형태	JSON에 쓸 때
`~`	`\~`	`\\~`
`^`	`\^`	`\\^`
`_`	`\_`	`\\_`
`[` `]`	`\[` `\]`	`\\[` `\\]`
`*`	`\*`	`\\*`
`<` `>`	`\<` `\>`	`\\<` `\\>`
`{` `}` `\|` `$` ` `\`	각각 escape	이중 escape

Bold는 escape 안 함: **텍스트**는 그대로 **텍스트**.

old_str에 escape된 문자 포함 시 주의: - 본문에 \~가 literal로 저장되어 있으면 (noton fetch 결과에서 보이면) - JSON 파라미터로 전달할 때 "\\~"로 이중 escape

Bookmark 블록 한계¶

Notion 북마크 블록은 Enhanced Markdown에서 <unknown url="..." alt="bookmark"/>로 직렬화됨. - URL을 직접 바꿀 수 없음 - 해결책 A: content_updates로 <unknown ... alt="bookmark"/> 전체를 일반 링크 [텍스트](URL)로 교체 → 북마크 카드 모양은 사라지고 텍스트 링크로 바뀜 - 해결책 B: Notion UI에서 북마크 블록 삭제 후 새 URL로 재등록

명령 유형¶

notion-update-page의 command 필드: - update_content: 부분 치환 (가장 안전, 기본값) - update_properties: DB 페이지의 속성만 수정 - replace_content: 페이지 본문 전체 교체 (자식 페이지/DB가 있으면 삭제 에러 발생) - apply_template: 템플릿 적용 - update_verification: 검증 상태 변경

Gmail: 실전 사용 예시¶

초안 작성 (보내지 않음, 검토용)¶

gmail_create_draft(
  to = "recipient@example.com",
  subject = "제목",
  body_html = "<p>내용</p>",
  instructions = "..."
)

바로 발송¶

gmail_send_email(...)

- 주의: 발송은 되돌릴 수 없음. 민티 글로벌 규칙상 "공유 상태 변경은 확인 먼저". 먼저 create_draft로 만들고 Gmail UI에서 검토 후 발송을 권장

메일 검색¶

gmail_find_email(search_string = "from:someone@example.com after:2026/04/01")

Google Calendar: 실전 사용 예시¶

이벤트 생성¶

google_calendar_create_detailed_event(
  calendar = "primary",
  summary = "제목",
  start_date_time = "2026-05-02T10:00:00+09:00",
  end_date_time = "2026-05-02T11:30:00+09:00",
  description = "..."
)

빠른 추가 (자연어)¶

google_calendar_quick_add_event(
  calendar = "primary",
  text = "5월 2일 오전 10시 위너책쓰기 31기 런칭모임"
)

Google Drive: 실전 사용 예시¶

파일 검색¶

google_drive_find_a_file(search_value = "31기 일정")

텍스트로 새 파일 만들기¶

google_drive_create_file_from_text(
  file_name = "메모.txt",
  file_content = "내용",
  folder = "폴더 ID"
)

파일 업로드¶

google_drive_upload_file(
  file = "file path or URL",
  folder = "..."
)

Make (시나리오 실행)¶

Zapier에서 Make(옛 Integromat) API를 호출할 수 있음. 복잡한 자동화 워크플로우를 외부에서 트리거.

make_api_mutating_request(
  method = "POST",
  url = "https://hook.make.com/..."
  body = {...}
)

비용 관리 팁¶

Zapier 100 tasks/월 한도를 고려한 전략:

한 번에 여러 치환: Notion의 content_updates는 배열 하나로 여러 치환을 묶을 수 있음 → 1회 호출로 12건 처리 (세션 한 번에 여러 치환 하는 게 훨씬 효율)
Google Docs find_and_replace는 1회 = 1건만: 여러 치환 필요하면 여러 번 호출해야 함. 묶을 수 없음. → 이게 tasks 많이 씀
검증 fetch는 필요할 때만: 치환 4~5건 할 때마다 한 번 fetch해서 확인하면 충분
무료 한도 근처일 때: 큰 작업(기수 전환 등)은 월 한 번으로 몰아서. 월 초에 몰아하면 여유 확보

알려진 버그/이슈¶

Zapier find_and_replace `output_hint` 해석 이슈¶

output_hint에 따라 응답의 results 필드가: - 치환 건수 (올바름): "output_hint": "total number of replacements" 같이 명확 - .results | length 값 (부정확, 보통 1): 모호한 hint일 때

해결: 명확한 영어 문구 사용 ("total replacements count", "number of replacements")

Zapier의 `followUpQuestion` 차단¶

간혹 치환 요청에 followUpQuestion으로 응답하며 실행 안 될 때가 있음. 해결: instructions 필드에 case-sensitive 같은 세부사항을 명시적으로 써주면 바로 실행됨

instructions = "Replace X with Y. Case-sensitive matching required."

실전 적용 사례¶

2026-04-24: 위너책쓰기 31기 공지 인프라 세팅¶

Google Docs: 긴 마스터 공지 문서(수천 줄)를 30→31기 전면 전환 (치환 약 30회, 약 60 Zapier tasks)
Notion: 31기 안내 페이지를 30기 복사본에서 31기로 (12건 한 번에 update_content + bookmark 블록 교체 1건)
워크플로우 재활용 문서: ~/.claude/projects/D--ebook-project/memory/new_cohort_setup_workflow.md

교훈 (민티 피드백 기반)¶

"기계적으로 하지 말고 내용을 확인해서 정확히": 전역 치환 돌리기 전에 문서 구조를 섹션별로 파악 → 맥락에 안 맞는 치환 방지
"찬찬히 실수 안 나오게": 치환 4~5건마다 fetch로 검증
"링크는 1주차 링크만, 나머지는 그대로": 어느 범위까지 바꿀지 명확히 사용자와 합의 후 진행

참고¶

전역 메모리 (연결 상태): ~/.claude/memory/mcp_tools_available.md
MCP 개념 (ComfyUI, Notion 등): 04-mcp.md
Zapier 대시보드: https://zapier.com/app/mcp
Notion MCP 공식: https://developers.notion.com/docs/mcp