@joberhr/jober-mcp

자버(jober) 카카오 알림톡·이메일 캠페인을 Claude, Cursor, VS Code 같은 AI 도구에서 바로 다루는 MCP 서버입니다. 문자 원문을 붙여 넣으면 알림톡(또는 이메일) 캠페인으로 바꾸고, 버튼에 내 링크나 설문 랜딩을 붙이고, 수신자를 등록하고, 발송과 결과 조회까지 할 수 있습니다. 서버가 돌려주는 guide(물을 질문과 다음에 부를 툴)를 따르면 적은 호출로 끝까지 갈 수 있습니다.

처음이세요?

1. 자버 계정이 없으면 https://jober.io/start/ai?src=mcp&client=local 에서 직접 가입하세요. 가입하면 바로 이메일·알림톡을 보낼 수 있습니다(가입 보너스 500원으로 약 10건). 다만 카카오 채널을 연동하기 전에는 이메일과 알림톡을 합쳐 체험 10건까지이고, 충전해도 늘지 않습니다. 10건을 넘겨 보내려면 카카오 채널을 연동하고 충전하세요.

2. 설정 > AI 도구 연동에서 개인 API 키(jbr_live_...)를 발급해 JOBER_API_KEY 에 넣고 MCP 서버를 다시 시작하세요. 키 없이 원격 URL 을 OAuth 로 연결해도 됩니다.

3. 키 없이 먼저 설치해도 됩니다. 키가 없거나 형식이 틀리면 종료하지 않고 안내 전용 모드로 떠서 get_started 툴 하나로 가입·키 발급·설정 방법을 알려 줍니다.

이 패키지는 로컬(stdio) MCP 서버입니다. 자체 로직 없이 자버 원격 MCP 서버(https://api.jober.io/mcp, Streamable HTTP)에 tools/list·tools/call 을 그대로 전달하고, 인증은 개인 API 키(Authorization: Bearer <JOBER_API_KEY>)로 합니다. 원격 MCP 를 직접 지원하는 클라이언트라면 이 패키지 없이 원격 URL 로 바로 연결해도 됩니다. MCP 클라이언트에 보이는 서버 표시 이름(title)은 원격과 같은 Jober (자버) 알림톡·이메일 AI 에이전트 이고, 서버 이름(name)은 jober-mcp 입니다.

English summary

할 수 있는 일

• 사전 확인(get_send_readiness): 카카오 채널 연동, 발송 한도의 남은 수(limits)와 안내(notices), 쓸 수 있는 기능, 야간 여부, 권한

• 원문 한 번에 초안 만들기(draft_send): 변환 + 내 링크 붙이기 + 페이지 생성 시작 + 명단 확인을 한 번에, 질문은 answer_questions 로 한 번에 답하기

• 문자(SMS) 원문을 알림톡 캠페인 초안으로 변환 (정보성 / 광고성 판별, 서식 추천, 빠진 값 질문). 광고 원문이면 앞에는 받은 혜택 안내만 남기고 홍보 내용은 버튼 뒤로

• 캠페인 수정 (발송명, 변수 값, 서식 변경, 정보성 안내의 수신거부 링크 끄기)

• 버튼에 내 링크 붙이기(메시지+링크), 설문 랜딩 페이지 생성 또는 기존 설문 선택

• 연락처 목록 미리보기와 등록 (전화번호 정규화, 중복 제거, 개인화 변수 연결)

• 발송 준비(대상 수, 예상 비용, 미리보기, 확인값 발급) 후 발송 또는 예약. 광고성 알림톡을 밤에 준비하면 묻지 않고 예약 시각 이후 첫 08:00(한국 시간)으로 예약(정보성 알림톡과 이메일은 야간에도 바로 발송)

• 예약 발송 취소, 발송 결과(전달·열람·응답) 조회, 미열람·미응답자 재알림 준비

• 이메일 캠페인: draft_send 에 channel: "EMAIL" 을 넣으면 같은 흐름(초안 → 질문 → 준비 → 발송 → 결과)으로 이메일을 보냅니다. 광고성 이메일은 서버가 제목의 (광고)·수신거부·발신자 정보를 넣습니다. 정보성 이메일에는 (광고)·보낸 곳을 넣지 않고 수신거부 링크만 기본으로 넣습니다

Related MCP server: xmit-mcp

보낼 수 있는 채널

• 실제로 쓸 수 있는지는 get_send_readiness 의 channels[](순서 EMAIL·KAKAO·SMS)와 onboarding.nextStep 으로 확인하세요. 이메일은 서버 설정에 따라 아직 열려 있지 않을 수 있습니다(404 J_41_20_1_2).

• channel 을 넣지 않은 기존 호출은 모두 알림톡(KAKAO)으로 동작합니다. 카카오 채널 미연동 스페이스는 기본으로 이메일과 알림톡이 체험 10건을 함께 씁니다(notices 의 EMAIL_SHARES_KAKAO_TRIAL). 충전해도 이 10건은 늘지 않습니다. 서버 설정에 따라 체험 공유 대신 가입 초기 하루 200명 상한이 걸릴 수 있으니 실제 값은 channels[EMAIL].quota 로 확인하세요.

• 보낼 인원이 정해졌으면 get_send_readiness 에 targets 를 넣으세요. channels[].capacity 에 지금 보낼 수 있는 수(now), 모자란 수(shortBy), 해제 방법(unlock: 충전 CHARGE·카카오 채널 연동 CONNECT_KAKAO_CHANNEL·다음 날 WAIT_DAILY_RESET)이 나옵니다.

• 잔액이 부족하면 409 J_41_23_1_14 이고, data.prepaidUrl(충전)·data.pricingUrl(요금제)을 사용자에게 알려 주면 됩니다.

준비물

• Node.js 18 이상

• 자버 계정·스페이스. 없으면 https://jober.io/start/ai?src=mcp&client=local 에서 사람이 직접 가입합니다(계정을 만드는 API·툴은 없습니다).

• 카카오 채널 연동은 권장이며 필수가 아닙니다. 연동하지 않으면 자버 공용 채널로 웹 발송과 같은 한도(체험 10건 등) 안에서 보내고, 외부 링크·광고 쿠폰 알림톡은 스페이스 누적 3명까지입니다(발송을 나눠도 합산, 이메일은 해당 없음)(채널 미연동 발송 한도).

• 자버 개인 API 키: https://jober.io/settings/integrations (설정 > AI 도구 연동 > 개인 API 키)에서 스페이스 관리자가 발급합니다. 키(jbr_live_...)는 발급 직후 한 번만 보이므로 안전한 곳에 보관하세요. 필요 없어진 키는 같은 화면에서 바로 폐기할 수 있습니다. 같은 화면의 회사 API 키(jbr_co_...)는 사내 서버 연동(발송 API·자유 발송 REST)용이라 MCP 에는 쓸 수 없습니다(이 패키지에 넣으면 안내 전용 모드로 뜨고, 원격 URL 헤더로 보내면 HTTP 401).

설치

아래 예시의 jbr_live_xxxxxxxx 를 발급받은 키로 바꾸세요. 키를 저장소에 커밋하지 마세요.

Claude Code

claude mcp add jober -e JOBER_API_KEY=jbr_live_xxxxxxxx -- npx -y @joberhr/jober-mcp

Claude Desktop

claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\)

{
  "mcpServers": {
    "jober": {
      "command": "npx",
      "args": ["-y", "@joberhr/jober-mcp"],
      "env": {
        "JOBER_API_KEY": "jbr_live_xxxxxxxx"
      }
    }
  }
}

Cursor

~/.cursor/mcp.json (전역) 또는 프로젝트의 .cursor/mcp.json

{
  "mcpServers": {
    "jober": {
      "command": "npx",
      "args": ["-y", "@joberhr/jober-mcp"],
      "env": {
        "JOBER_API_KEY": "jbr_live_xxxxxxxx"
      }
    }
  }
}

VS Code

.vscode/mcp.json (키는 처음 실행할 때 입력 창으로 받습니다)

{
  "inputs": [
    {
      "type": "promptString",
      "id": "jober-api-key",
      "description": "Jober API key (jbr_live_...)",
      "password": true
    }
  ],
  "servers": {
    "jober": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@joberhr/jober-mcp"],
      "env": {
        "JOBER_API_KEY": "${input:jober-api-key}"
      }
    }
  }
}

원격 URL 직접 연결 (OAuth)

원격 MCP(Streamable HTTP)를 지원하는 클라이언트는 패키지 설치 없이 https://api.jober.io/mcp 를 추가하면 됩니다. 처음 연결할 때 브라우저에서 자버 로그인과 권한 동의 화면이 열리고, 허용하면 OAuth 2.1(PKCE) 토큰으로 연결됩니다. claude.ai·ChatGPT 의 사용자 지정 커넥터에도 같은 주소를 넣으면 됩니다.

연결을 끊으려면 자버 웹의 설정 > AI 도구 연동의 연결된 AI 도구 목록에서 해당 앱의 [연결 끊기]를 누르세요. 끊는 즉시 그 연결의 토큰이 모두 폐기되어 이후 호출은 401 이 됩니다. API 키는 같은 화면의 API 키 목록에서 폐기합니다.

# Claude Code
claude mcp add --transport http jober https://api.jober.io/mcp

// Cursor (mcp.json)
{ "mcpServers": { "jober": { "url": "https://api.jober.io/mcp" } } }

// VS Code (.vscode/mcp.json)
{ "servers": { "jober": { "type": "http", "url": "https://api.jober.io/mcp" } } }

OAuth 대신 개인 API 키를 쓰려면 Authorization: Bearer jbr_live_xxxxxxxx 헤더를 넣으세요 (예: claude mcp add --transport http jober https://api.jober.io/mcp -H "Authorization: Bearer jbr_live_xxxxxxxx").

안내 전용 모드 (키가 없을 때)

JOBER_API_KEY 가 비어 있거나, 개인 API 키 모양(jbr_live_ + 영문·숫자 32자 이상)이 아니거나, 회사 API 키(jbr_co_)면 종료하지 않고 안내 전용 모드로 시작합니다.

• 원격 MCP(/mcp)에 연결하지 않고, 툴은 get_started 하나만 노출합니다. 서버 안내문(instructions)이 AI 도구에 get_started 를 부르라고 알려 줍니다.

• get_started 는 자버 공개 안내 <JOBER_API_BASE>/ai-agent/v2/public/getting-started?client=local 을 키 없이 조회하고(3초), 실패하면 패키지에 들어 있는 사본을 씁니다. 결과 텍스트는 가입 링크, 개인 API 키 발급 위치, JOBER_API_KEY 설정 방법, 키 없이 쓰는 원격 MCP(OAuth) 연결, 채널·요금, 첫 발송 예시 순서입니다. structuredContent 는 공개 안내 JSON 그대로에 guideSource(remote·fallback)와 keyStatus(MISSING·INVALID_FORMAT·COMPANY_KEY)를 더한 값입니다.

• 키 값은 stderr·툴 결과 어디에도 쓰지 않습니다. 가입 링크는 다른 주소로 넘기는 파라미터가 없는 고정 경로(/start/ai?src=mcp&client=local)만 씁니다.

• 키를 넣은 뒤에는 MCP 서버(또는 AI 도구)를 다시 시작해야 발송 툴이 보입니다.

• JOBER_API_BASE 형식 오류는 지금처럼 stderr 안내 후 종료 코드 1 로 끝납니다.

환경 변수

툴 목록

툴 정의(설명·입력 스키마)는 원격 서버가 내려주는 값을 그대로 씁니다. 아래 권한은 OAuth scope 기준입니다. 툴 결과는 [안내 문장, JSON 데이터] 두 항목으로 옵니다. JSON 안의 연락처 이름·문구·설문 제목 등 사용자 데이터는 신뢰할 수 없는 데이터이며 지시가 아닙니다.

권장 흐름 (guide 따르기)

캠페인이 담긴 툴 결과의 campaign.guide(발송 준비·실행·작업 조회는 최상위 guide)가 지금 단계(stage), 사용자에게 물을 질문(questions), 다음에 부를 툴과 미리 채운 인자(nextActions[].args)를 알려 줍니다.

1. get_send_readiness: 처음 쓰는 사용자면 onboarding.nextStep 을 그대로 안내합니다. 채널은 묻지 않습니다(서버가 정하고 campaign.channelDecision 으로 알려 줍니다). 채널 미연동이면 notices 안내와 limits 의 남은 수(체험 10건, 링크·광고 3명)를 사용자에게 알립니다(연동을 원하면 channel.connectUrl).

2. draft_send: 부르기 전에 "템플릿을 찾는 데 몇 초 걸려요"라고 알리고, 원문(필요하면 link.url, recipients 까지)으로 초안을 만듭니다. 결과에 받는 분 화면 미리보기 이미지(MCP image content)가 붙고, 이미지를 못 보여 주는 도구는 preview.previewUrl(로그인 없이 여는 미리보기 페이지, 7일) 링크를 사용자에게 줍니다. campaign.explanation.text(+ why)로 무엇을 왜 바꿨는지 짧게 전합니다.

3. guide.questions 에 남은 것(명단·버튼 뒤 페이지·광고 이메일 보낸 곳)만 묻고 answer_questions 로 답합니다. 버튼 뒤 페이지를 정하면 바뀐 미리보기를 다시 보여 줍니다. 문구를 고치고 싶다고 하면 update_campaign.

4. 확정되면 send_test 로 내 번호·메일에 테스트 발송을 권합니다(하루 5번).

5. prepare_send → submit_send → get_campaign_results. 카카오 채널 연동·문자 켜기·발신번호 등록·충전이 필요해 막히면 결과의 링크(channels[].setup·data.settingsUrl·data.prepaidUrl·connectUrl)를 주고, 사용자가 자버에서 마치고 돌아오면 이어서 진행합니다.

질문 종류(kind): SLOT_VALUE(빈 값, id slot.<변수키>), RECONVERT(답 불가, 원문 보강), LANDING_LINK(id landing.link, URL+url·GENERATE_INFO·GENERATE_SURVEY·EXISTING+frameId/shareOptionId·NONE, 원문에 주소가 있으면 그 주소를 추천), SEND_LIMIT_EXCEEDED(답 불가, stage BLOCKED, 명단이 한도의 남은 수보다 많음, context: {code, remaining, limit, targets, connectUrl}, 선택지 받는 사람 줄이기·채널 연동·요금제 확인), CHANNEL_REQUIRED(비상시에 채널 연동을 다시 필수로 켰을 때만, 답 불가), RECIPIENTS(id recipients, headers·rows), COLUMN_MAPPING(id recipients.columnMap). 광고·정보성(NATURE_CHOICE)과 수신 동의(SEND_BASIS)는 서버가 더 묻지 않습니다(값은 하위 호환으로만 남음): 광고·정보성은 서버가 정하고, 광고면 prepare_send 의 consentConfirmed: true 로 수신 동의(쿠폰 안내는 혜택 지급까지)를 한 번 확인합니다. 사용자가 정보성으로 바꾸고 싶다고 하면 answer_questions 의 {id: "nature", value: "INFO"} 나 update_campaign 의 natureChoice 로 보냅니다. 야간 시각과 수신거부는 묻지 않습니다. 채널 미연동이어도 링크 질문에는 모든 선택지가 나오고, 링크·광고 3명 상한의 남은 수가 0 이면 URL 만 빠집니다.

캠페인 상태

status 는 저장된 값이 아니라 조회할 때마다 서버가 발송 작업과 스팸 검토 기록으로 계산합니다(웹·MCP·REST 동일).

• pendingOperation.status 는 SUBMITTING 하나입니다(UNKNOWN 은 더 이상 오지 않습니다). 접수가 5분 안에 끝나지 않으면 서버가 정리해 READY 로 돌아갑니다.

채널 미연동 발송 한도

카카오 채널 연동은 필수가 아닙니다. 연동하지 않으면 자버 공용 채널로 웹과 같은 검사(스팸·공용 채널 금지 표현·구독·선불 잔액)를 거쳐 보냅니다. limits[] 항목은 {code, applies, limit, used, remaining, exempt, errorCode} 입니다.

• 실리는 곳: get_send_readiness 의 limits, 발송 전 캠페인의 campaign.limits, prepare_send 의 summary.limits, 한도 거절의 data.limits. notices[] 는 UNCONNECTED_PUBLIC_PROFILE·TEST_SEND_CHARGE·QUIET_HOURS_SUBSCRIPTION, subscriptionRequiredFor 는 구독이 없으면 ["SCHEDULED", "VARIABLE_LINK"] 입니다.

• 채널 미연동이어도 링크 버튼 템플릿으로 보냅니다. 목적지가 있는데 맞는 버튼 템플릿이 없으면 409 J_41_23_4_4(NO_BUTTON_TEMPLATE)로 막고, 버튼 없이 바꿔 보내지 않습니다.

• J_41_23_1_10(채널 미연동 거절)은 자버가 비상시에 채널 연동을 다시 필수로 켰을 때만 납니다. J_41_23_1_4 는 더 이상 내지 않습니다.

내 링크 붙이기 (메시지+링크)

draft_send 의 link.url, landing.link 의 URL 답, set_direct_link 는 같은 기능입니다. 알림톡 버튼을 누르면 그 주소가 열립니다.

• 붙이기 전에 주소와 도메인(쿼리 속 리다이렉트 목적지 포함)을 스팸 기준으로 검사합니다.

• http·https 공개 주소, 500자 이하만 됩니다. 사설 IP·localhost·.internal·아이디/비밀번호가 든 주소는 400 J_41_22_1_12, 버튼 주소가 고정된 템플릿은 J_41_22_1_13, 스팸 판정 차단은 J_41_22_1_14(data.restrictedKeywords), 검사할 내용이 너무 길면 J_41_22_1_15 입니다.

• 단축 주소는 막지 않지만 신고될 수 있으니 원래 주소를 권하세요. 자버 공유 링크는 공유 페이지(SELECT_SHARE)로 바꿔 붙입니다.

• 받는 사람 모두 같은 링크입니다. 결과의 열람은 버튼을 누른 수이고 응답은 null 입니다. 광고·쿠폰 안내면 경고 LINK_LANDING_NOTICE(링크 첫 화면에 혜택 안내가 먼저 보이게)가 붙습니다.

발송 안전장치

실제 비용이 드는 발송은 웹과 같은 규칙으로 서버가 검사합니다. 이 패키지는 요청을 전달만 하므로 우회할 수 없습니다.

• 2단계 발송: prepare_send 가 대상 수·예상 비용·렌더된 미리보기와 operationUuid·confirmHash 를 돌려줍니다. submit_send 는 이 값과 새 idempotencyKey 로 호출하며, 준비 이후 대상·본문·서식·비용이 바뀌었으면 거부되어 다시 준비해야 합니다. 별도의 사람 승인 단계는 없고, 발송 가능 여부는 아래 서버 정책으로 판단합니다(자동화 워크플로에서도 그대로 동작).

• 멱등 키: submit_send 는 idempotencyKey 가 필수이며, 같은 키로 다시 호출해도 한 번만 발송됩니다. 이 패키지는 실패한 호출을 자동 재시도하지 않습니다.

• 접수 확인 대기: submit_send 가 409 J_41_23_4_5(pending)를 돌려주거나 get_campaign 에 pendingOperation(SUBMITTING)이 있으면, 같은 operationUuid·confirmHash·idempotencyKey 로 다시 호출해 결과를 받으세요. 키를 잃었으면 새 키로 보내지 말고 get_campaign 으로 상태만 다시 확인합니다(5분 안에 접수가 끝나지 않으면 서버가 READY 로 정리). J_41_23_4_5 의 lastErrorCode 는 마지막 오류 코드(거절 확정 아님)이고, 거절이 확정된 경우만 sourceErrorCode 로 옵니다.

• 풀리지 않는 거절: 구독·선불 잔액·연동비·발송 한도 같은 웹 발송 검증 거절은 J_41_23_1_9(data.sourceErrorCode = 원래 코드, data.sourceMessage = 원문 메시지)이며 needsPrepare 가 없습니다. 다시 준비해도 같은 결과이므로 원인을 해결한 뒤 진행하세요. prepare_send 도 이 검증을 미리 하므로 대부분 준비 단계에서 걸립니다.

• 다시 준비 여부: 실패 응답에 data.needsPrepare 가 있으면 prepare_send 부터 다시 하세요. 준비 만료(J_41_23_4_1), 확인값·상태 변경(J_41_23_4_2), 받는 사람 값 변경(J_41_23_2_1), 실패한 멱등 키 재시도(J_41_23_2_2) 등에 붙습니다. 아래 조건 거절(J_41_23_1_9)과 템플릿 변경(J_41_23_4_11, 원문 다시 변환 필요)에는 붙지 않습니다. J_41_23_4_2 에 data.status(발송 중·예약·완료·취소)가 있거나 같은 키 재시도 응답에 data.stopped 가 있으면 다시 준비하지 말고 get_campaign 으로 상태를 확인하세요.

• 결과 조회 상태: get_campaign_results 응답의 campaignStatus·canceledReason(SEND_STOPPED = 발송 중단·스팸 검토 거부, SCHEDULE_CANCELED = 예약 취소)은 get_campaign 과 같은 규칙으로 계산한 캠페인 상태이고, statsAvailable: false 면 집계할 발송 결과가 없습니다.

• 멈춘 제출: submit_send 가 409 J_41_23_4_9(data.superseded = true, notSent: true)를 돌려주면 접수 확인이 늦어져 이 요청은 발송 작업을 만들지 않고 멈춘 것입니다. data.reason 은 NEWER_SUBMISSION(새 제출이 먼저 접수) 또는 STALE_SUBMISSION(새 제출 없이 멈춤)입니다. 바로 다시 준비하지 말고 get_campaign 으로 상태를 확인하고, 캠페인이 READY·PREPARED 면 사용자 확인 뒤 prepare_send 부터 다시 할 수 있습니다.

• 확정값 발송: 예약 발송을 포함해 실제 발송은 submit_send 때 확정한 받는 사람(번호·이름)과 개인화 값으로 나갑니다. 그 뒤 연락처를 바꿔도 이미 확정한 발송 내용은 바뀌지 않습니다.

• 링크 없이 보내기: select_survey 의 NONE 은 같은 템플릿의 버튼 없는 변형으로 바꿔 보냅니다. 버튼 없는 변형이 없는 템플릿(get_campaign 의 noLinkAvailable: false)은 NONE 이 400 J_41_22_1_11 이니 연결할 링크를 골라 주세요.

• 개인화 변수 연결(재확정): commit_recipients 의 변수 연결은 매번 그 요청의 customColumnMap 기준으로 다시 정해집니다. 명단을 다시 확정할 때 기존 연결을 유지하려면 같은 칸에 variable 을 다시 지정하세요. variable 을 빼거나 그 칸을 빼면 연결이 풀리고(unboundVariables) 값을 다시 묻습니다.

• 수신자 제한: 발송 대상은 commit_recipients 로 서버에 등록된 캠페인 대상뿐이며, 전화번호를 발송 요청에 직접 넣을 수 없습니다.

• 야간 자동 예약(채널별): 야간 규칙은 채널별이에요. 광고성 알림톡만 밤 9시~아침 8시(한국 시간)에 보내지 않고, 그 시간에 준비하면 예약 시각 이후 첫 08:00(한국 시간)으로 자동 예약해요(summary.adjustments). 정보성 알림톡과 이메일(광고성 포함)은 야간에도 자동 예약 없이 바로 보내요. 이메일 prepare_send 에는 늘 EMAIL_NIGHT_ALLOWED 안내가 붙어요. 채널별 규칙은 get_send_readiness 의 quietHours.channels 에 있어요. 이 시간에 광고성 알림톡으로 prepare_send 를 부르면 묻지 않고 예약 시각 이후 첫 08:00(한국 시간)으로 예약하고 summary.adjustments(QUIET_HOURS_RESCHEDULED)로 알려 줍니다. 그대로 submit_send 하면 예약됩니다. 옮긴 날이 사용기한보다 뒤면 400 J_41_23_1_11, 같은 날이면 경고 EXPIRY_SAME_DAY. 지금 보내기로 준비했는데 submit_send 시점이 야간이면 400 J_41_23_1_2(data.needsPrepare: true)이니 prepare_send 를 다시 부르면 08:00 자동 예약이 됩니다.

• 채널 미연동 한도: 채널 연동은 필수가 아닙니다. 미연동이면 체험 10건(삭제 포함)과 외부 링크·광고 쿠폰 알림톡의 스페이스 누적 3명 상한(발송을 나눠도 합산, 409 J_41_23_1_13)을 prepare_send·submit_send 때 두 번 확인합니다. 다시 준비해도 풀리지 않으니 받는 사람을 줄이거나 채널을 연동하세요(채널 미연동 발송 한도).

• 연쇄 변경 중단: draft_send·answer_questions 도중 다른 요청이 캠페인을 바꾸면 성공 응답 안에서 남은 단계만 멈추고 skipped·failedSteps 에 J_41_21_4_2 + data.stoppedBy 가 남습니다. get_campaign 으로 최신 상태를 보고 다시 답하세요.

• 수신거부 링크 기본 켬: 정보성 안내까지 기본으로 붙습니다(정보성 이메일은 (광고)·보낸 곳 없이 수신거부만). 정보성만 update_campaign 의 optOutLink: false 로 끌 수 있습니다. 붙일 수 없는 템플릿이면 경고 OPT_OUT_UNAVAILABLE.

• 서버 정책 동일 적용: 스팸·금지 업종 차단, 광고성 메시지의 수신 동의 확인(prepare_send 의 consentConfirmed, 없으면 400 J_41_23_1_3), 1000자 제한, 잔액·발송 한도 검사.

• 사후 확인: 발송되면 스페이스 관리자에게 바로 알림이 가고, 예약 발송은 cancel_scheduled_send 나 웹에서 취소할 수 있습니다.

• 키 관리: 개인 API 키는 발급한 관리자 개인에게 귀속되고 서버에는 해시로만 저장됩니다. 의심되면 설정 > AI 도구 연동에서 즉시 폐기하세요. 이 패키지는 키를 환경 변수로만 받고 https 로만 보냅니다.

문제 해결

연결 단계 오류(인증 401, 권한·MCP 사용·차단 403, 호출 한도 429, 404)는 HTTP 상태로 오고, 이 패키지가 아래 …(HTTP 401) 같은 메시지로 알려 줍니다. 툴 실행 중 오류는 HTTP 200 의 정상 JSON-RPC 응답으로 오며 result.isError: true 이고, content 안의 errorCode 로 판별합니다(아래 J_ 코드 행). 코드 옆 괄호의 숫자는 같은 코드의 자유 발송 API(REST) HTTP 상태이며 MCP 에서는 HTTP 상태로 오지 않습니다.

로그와 오류 메시지는 stderr 로만 출력됩니다(stdout 은 MCP 프로토콜 전용).

개발

npm install
npm test          # 타입 검사 + 빌드 + 단위 테스트(모의 원격 Streamable HTTP 서버로 프록시 검증)
JOBER_API_BASE=http://localhost:4100 JOBER_API_KEY=jbr_live_xxxxxxxx node dist/index.js
# PowerShell: $env:JOBER_API_BASE="http://localhost:4100"; $env:JOBER_API_KEY="jbr_live_xxxxxxxx"; node dist/index.js
JOBER_API_BASE=http://localhost:4100 node dist/index.js   # 키 없이 실행하면 안내 전용 모드(get_started)

내장 사본 src/guide-fallback.json 은 jober-api 공개 안내(GET /ai-agent/v2/public/getting-started) 응답과 같은 모양입니다. 원격 값이 바뀌면 함께 맞추세요.

English summary

@joberhr/jober-mcp is a local (stdio) MCP server for Jober. It turns text messages into KakaoTalk AlimTalk or email campaigns, attaches survey landing pages, imports recipients, sends or schedules campaigns and reports delivery, open and response results. It has no business logic of its own: it proxies tools/list and tools/call to the remote Jober MCP server (https://api.jober.io/mcp, Streamable HTTP) using your personal API key (jbr_live_) as Authorization: Bearer <JOBER_API_KEY>. Company API keys (jbr_co_) are for server integrations (send API, free-send REST) and cannot be used with MCP.

• New to Jober? Sign up yourself at https://jober.io/start/ai?src=mcp&client=local (there is no account-creation API), then create a personal API key.

• Guide-only mode: if JOBER_API_KEY is missing, malformed or a company key, the server does not exit. It exposes a single get_started tool that returns the signup link, where to create the key, how to set it and the remote OAuth alternative (fetched without a key from <JOBER_API_BASE>/ai-agent/v2/public/getting-started?client=local, with a bundled offline copy). Set the key and restart the server to get the campaign tools. An invalid JOBER_API_BASE still exits with code 1.

• Channels: EMAIL (right after signup, prepaid balance) and KAKAO (default) via draft_send's channel, and SMS for informational messages only (50 KRW each, must be enabled in Jober, channels[SMS]; ads are rejected with J_41_21_1_10). Omit channel and the server decides it (channelDecision). Check channels[] and onboarding.nextStep in get_send_readiness. Before a Kakao channel is connected, email and AlimTalk share the 10-send trial, and charging does not raise it; connect the channel and charge to send more (see channels[EMAIL].quota; pass targets to get_send_readiness for channels[].capacity). Insufficient balance is J_41_23_1_14 with data.prepaidUrl.

• Quiet hours: Only advertising Alimtalk sends in KST 21:00-08:00 are auto-scheduled for the first 08:00 KST after the requested time; informational Alimtalk and all emails are sent immediately. Email prepare_send always includes the EMAIL_NIGHT_ALLOWED notice. See quietHours.channels in get_send_readiness.

• Server name: the MCP server title is Jober (자버) 알림톡·이메일 AI 에이전트 (same as the remote server); the server name is jober-mcp.

• API key: create one at https://jober.io/settings/integrations (shown once; revoke it there at any time).

• Install: claude mcp add jober -e JOBER_API_KEY=jbr_live_xxxxxxxx -- npx -y @joberhr/jober-mcp, or use the npx -y @joberhr/jober-mcp command with the JOBER_API_KEY env var in Claude Desktop, Cursor or VS Code (snippets above).

• Remote (OAuth): clients that support remote MCP can connect to https://api.jober.io/mcp directly and sign in with OAuth 2.1 (PKCE).

• Env vars: JOBER_API_KEY (needed for the campaign tools; without it, guide-only mode), JOBER_API_BASE (default https://api.jober.io, https only except localhost).

• Tools: the 22 tools listed above (including send_test for one test recipient before the real send and edit_page to change the landing page as the user asks), including get_send_readiness, draft_send (convert + attach your link + start a landing page + check recipients in one call), answer_questions and set_direct_link (your own URL on the AlimTalk button, "message+link").

• Guide: results carry guide (stage, questions to ask the user, nextActions with prefilled args). Follow it and answer all questions with answer_questions.

• Kakao channel: connecting a Kakao channel is recommended but not required. Without one, sends go out through Jober's shared channel under the same limits as the web app (see limits in get_send_readiness), and external-link or ad-coupon sends are capped at 3 recipients per space in total, summed across sends (J_41_23_1_13; email is not affected). A destination without a link-button template is rejected with J_41_23_4_4 (NO_BUTTON_TEMPLATE). If the channel status lookup fails temporarily, prepare_send/submit_send return a tool error J_41_23_2_3 (HTTP 200 with result.isError: true; HTTP 503 on the REST API) without needsPrepare: retry later (for submit_send, the same confirm hash; reusing the same idempotency key or a new one are both safe).

• Campaign status: status is computed on every read (10 values: DRAFT, NEEDS_INPUT, READY, PREPARED, BLOCKED, SCHEDULED, SENDING, SENT, CANCELED, FAILED). pendingOperation.status is only SUBMITTING; UNKNOWN is no longer returned.

• Send safety: two-step prepare_send then submit_send with a confirm hash and a required idempotency key (no separate human approval step), recipients limited to those committed on the server, the same server-side policies as the web app (spam blocking, opt-out text, ad consent, quiet hours per channel (only advertising Alimtalk sends prepared between 21:00 and 08:00 KST are rescheduled to the first 08:00 KST after the requested time without asking, while informational Alimtalk and all emails including ads are sent immediately; see quietHours.channels) reported in summary.adjustments, the opt-out link on by default (only informational campaigns may turn it off), 1000-character limit, balance and send limits), instant admin notification and cancellable scheduled sends. The proxy never retries failed calls automatically.

License

MIT