시작하기

guide — 온보딩/사용법 안내 ★ 먼저 호출

처음 사용 시 가장 먼저 호출하는 도구입니다. 도구 목록, 요금, 발송 흐름을 주제별로 안내합니다.

{
  "topic": "all"  // all | sms | email | mms | alimtalk | image | pricing | report (기본: all)
}

💰 무료

send_sms — 단문 문자 발송

90자 이내의 단문 문자(SMS)를 발송합니다.

{
  "receiver": "01012345678",  // 수신번호
  "message": "안녕하세요, 내일 오전 10시 미팅입니다."  // 최대 90자
}

💰 단가: 17원/건

send_lms — 장문 문자 발송

2,000자 이내의 장문 문자(LMS)를 발송합니다.

{
  "receiver": "01012345678",
  "message": "안녕하세요.\n\n이번 행사 안내를 드립니다.\n..."  // 최대 2000자
}

💰 단가: 40원/건

send_bulk — 대량 문자 발송

여러 수신자에게 동일한 문자를 한 번에 발송합니다.

{
  "receivers": ["01012345678", "01087654321", "01099998888"],
  "message": "공지 내용입니다.",
  "type": "SMS"  // "SMS" 또는 "LMS"
}

💰 단가: 타입에 따라 건당 동일 요금

send_mms — MMS 이미지 문자 발송

서버에 업로드된 이미지 경로(imagePath)로 MMS를 발송합니다. 이미지는 JPG/PNG/GIF 형식, 최대 2MB까지 지원합니다. 먼저 get_upload_url 또는 send_mms_upload로 이미지를 업로드해 savedPath를 받은 뒤 호출합니다.

{
  "receiver": "01012345678",
  "message": "이미지와 함께 발송하는 MMS입니다.",
  "imagePath": "/opt/imsend/uploads/mms/1700000000_photo.jpg"
}

💰 단가: 90원/건

send_mms_now — Base64 MMS 통합 발송

Base64 이미지를 1번 호출로 업로드+발송합니다. 파일 없이 즉시 보낼 때 사용하며, Claude.ai 본문에서 안정적입니다(GPT 환경은 truncation 주의). 서버에서 자동 640px 리사이즈 + JPG 변환합니다.

{
  "receiver": "01012345678",
  "message": "이미지 보내드립니다.",
  "imageBody": "Base64인코딩값",  // JPG/PNG/GIF, 최대 2MB
  "imageName": "photo.jpg"        // 선택 (기본: image.jpg)
}

💰 단가: 90원/건

send_mms_upload — Base64 이미지 업로드 구버전

Base64 이미지를 서버에 업로드하고 savedPath/imageUrl을 반환합니다. 반환된 savedPath를 send_mms의 imagePath로 사용합니다. ⚠️ GPT 환경에서 truncation이 발생할 수 있어 send_mms_now 또는 업로드 세션 방식을 권장합니다.

{
  "imageBody": "Base64인코딩값",  // JPG/PNG/GIF, 최대 2MB
  "imageName": "photo.jpg"        // 선택 (기본: image.jpg)
}

💰 무료 (발송은 send_mms 단가 적용)

get_upload_url — Pre-signed 업로드 URL 발급

MMS 이미지 또는 이메일 본문 이미지를 업로드할 URL을 발급합니다. AI가 curl/requests로 직접 binary 업로드하므로 Base64 방식보다 빠르고 대용량에 적합합니다.

📱 MMS 이미지 업로드 (3단계)

# 1단계: 업로드 URL 발급 (send_mms 도구 사용)
get_upload_url(type="mms", fileName="photo.jpg")
# → uploadUrl, savedPath 반환

# 2단계: AI가 직접 이미지 PUT 업로드 (bash)
curl -X PUT "https://mcp.imsend.kr/mcp/upload/{token}" \
     --data-binary @photo.jpg \
     -H "Content-Type: application/octet-stream"
# 또는 Python
# import requests
# requests.put(uploadUrl, data=open('photo.jpg','rb'), headers={'Content-Type':'application/octet-stream'})

# 3단계: MMS 발송
send_mms(receiver="01012345678", message="이미지 발송", imagePath="{savedPath}")

📧 이메일 본문 이미지 업로드 (3단계)

# 1단계: 업로드 URL 발급
get_upload_url(type="email", fileName="banner.png")
# → uploadUrl, savedPath, imageUrl 반환

# 2단계: 이미지 PUT 업로드
curl -X PUT "https://mcp.imsend.kr/mcp/upload/{token}" \
     --data-binary @banner.png \
     -H "Content-Type: application/octet-stream"

# 3단계: 이메일 발송 (imageUrl을 본문에 삽입)
send_email(to="user@example.com", subject="...", content="<img src='https://imsend.kr/uploads/email/...'>")

🔄 환경별 권장 업로드 방식

💰 무료 (발송 시 해당 도구 단가 적용)

get_image_upload_url — 이미지 업로드 페이지 URL 발급 ★ 권장

사용자가 브라우저에서 직접 이미지를 올릴 수 있는 전용 업로드 페이지를 발급합니다. Base64 변환 없이 MMS/이메일 이미지를 처리하는 권장 방식입니다. Claude웹·ChatGPT웹·모바일 모든 환경에서 동작합니다.

파라미터

반환값

{
  "uploadPageUrl": "https://mcp.imsend.kr/mcp/image-upload/{token}",
  "token": "{token}",
  "expiresIn": "15분",
  "instruction": "아래 URL을 사용자에게 안내하세요. 업로드 완료 후 check_upload_status를 호출하세요.",
  "nextStep": "check_upload_status(token)"
}

전체 흐름 (MMS 예시)

# 1단계: 업로드 링크 발급
get_image_upload_url(type="mms")
→ uploadPageUrl: "https://mcp.imsend.kr/mcp/image-upload/abc123"

# 2단계: 사용자에게 안내
"이미지를 여기서 업로드해주세요 (15분 유효):
 https://mcp.imsend.kr/mcp/image-upload/abc123"

# 3단계: 사용자가 링크 클릭 → 파일 선택 → 업로드

# 4단계: 업로드 완료 확인
check_upload_status(token="abc123")
→ { done: true, imageUrl: "https://imsend.kr/uploads/mms/xxx.jpg" }

# 5단계: MMS 발송
send_mms_from_url(receiver="01012345678", message="이미지 발송", imageUrl="https://imsend.kr/uploads/mms/xxx.jpg")

🤖 ChatGPT 환경 (Python container)

# 1단계: get_image_upload_url(type="mms") 로 token 발급
# 2단계: ChatGPT Python container에서 실행
import requests
files = {"file": open("/mnt/data/photo.jpg", "rb")}
r = requests.post(
    "https://mcp.imsend.kr/mcp/image-upload/{token}",  # token 교체
    files=files
)
result = r.json()
# result: {"success": true, "imageUrl": "https://imsend.kr/uploads/mms/xxx.jpg"}

# 3단계: MCP 도구 호출
# send_mms_from_url(receiver="01012345678", message="발송내용", imageUrl=result["imageUrl"])

check_upload_status — 업로드 완료 확인

get_image_upload_url 발급 후 사용자가 이미지를 업로드했는지 확인합니다. 완료 시 imageUrl을 반환합니다.

파라미터

반환값 예시

// 완료 시
{ "done": true, "imageUrl": "https://imsend.kr/uploads/mms/xxx.jpg", "fileName": "photo.jpg", "fileSize": 512000 }

// 대기 중
{ "done": false, "message": "아직 업로드 중입니다. 잠시 후 다시 확인하세요." }

// 만료
{ "done": false, "expired": true, "message": "토큰이 만료됐거나 존재하지 않습니다." }

send_mms_from_url — URL로 MMS 발송 ★ 권장

이미지 URL로 MMS를 발송합니다. check_upload_status에서 받은 imageUrl 또는 공개 이미지 URL을 사용합니다. Base64 없음.

파라미터

send_mms_from_url(
  receiver="01012345678",
  message="이미지 보내드립니다.",
  imageUrl="https://imsend.kr/uploads/mms/1234567890_photo.jpg"
)

send_email — 이메일 발송

HTML을 지원하는 이메일을 발송합니다. 파일 첨부도 지원합니다.

// 기본 발송
{
  "to": "user@example.com",
  "subject": "이메일 제목",
  "content": "<h1>안녕하세요</h1><p>이메일 내용입니다.</p>"
}

// 파일 첨부 발송
{
  "to": "user@example.com",
  "subject": "첨부파일 포함 이메일",
  "content": "<p>파일을 첨부했습니다.</p>",
  "attachments": [
    { "fileName": "report.pdf", "fileBody": "JVBERi0xLjQ..." }
  ]
}

💰 단가: 1.5원/건

send_email_now — 이메일 통합 발송 (본문 이미지 1-step) ★ 권장

Base64 이미지 1번 전달로 본문 자동 삽입 후 이메일을 발송합니다. content에 {{IMAGE_URL}} 플레이스홀더를 두면 그 위치에, 없으면 본문 하단에 자동 삽입됩니다. 이미지 없이 텍스트만 보내도 됩니다.

{
  "to": "user@example.com",
  "subject": "이미지 포함 이메일",
  "content": "<p>본문입니다.</p>{{IMAGE_URL}}",
  "imageBody": "Base64값",
  "imageName": "banner.jpg"
}

💰 단가: 1.5원/건

create_mms_upload_session — MMS 자동발송 세션 ★★ 전 환경 1순위

MMS 이미지 발송을 위한 자동발송 세션을 생성합니다. 업로드 링크를 사용자에게 안내하면, 사용자가 이미지를 업로드하는 즉시 서버가 자동으로 MMS를 발송하고 페이지에서 결과를 표시합니다. AI 폴링 불필요 · Claude/GPT/모바일 통일

파라미터

전체 흐름

# 1단계: AI가 세션 생성
create_mms_upload_session(receiver="01012345678", message="이미지 보내드립니다")
→ { sessionId, uploadPageUrl, expiresIn: "15분" }

# 2단계: AI가 사용자에게 링크 안내
"이미지를 여기서 업로드해주세요: [링크]"

# 3단계: 사용자가 링크 클릭 → 이미지 선택 → 업로드
→ 서버: PNG/WEBP → JPG 640px 자동 변환
→ 서버: MMS 자동 발송
→ 페이지: "✅ 문자 전송이 완료되었습니다!" 표시 → 자동 닫힘(PC) / 닫기 버튼(모바일)

# 4단계 (선택): AI가 결과 확인
get_mms_upload_session_status(sessionId)
→ { uploaded: true, sendStatus: "DELIVERED", mseq: 12345 }

💰 단가: 90원/건

create_image_upload_session — curl 자동화 업로드 세션 ★ bash 자동화

Claude Desktop 등 bash 실행 환경에서 로컬 파일을 curl -F로 업로드하기 위한 세션을 생성합니다. 응답의 curl 명령으로 업로드한 뒤 send_mms_from_session으로 발송합니다(사람/브라우저 개입 불필요).

// 파라미터
{ "receiver": "01012345678", "message": "이미지 보내드립니다." }
// 응답
{ "session_id": "...", "upload_url": "...", "curl": "curl -F \"file=@/path/to/image.jpg\" \"...\"", "expires_in": 900 }

💰 무료 (발송은 MMS 90원/건 적용)

send_mms_from_session — 세션으로 MMS 발송

create_image_upload_session의 session_id로 업로드된 이미지를 MMS 발송합니다. 중복 호출해도 1회만 발송됩니다(idempotent). wait/wait_timeout_sec로 발송 결과까지 대기할 수 있습니다.

{
  "session_id": "...",          // create_image_upload_session의 session_id
  "wait": true,                  // 선택, true면 60초 대기(별칭)
  "wait_timeout_sec": 60          // 선택, 0=즉시반환 (1~110, 초과 시 110 클램프)
}

💰 단가: 90원/건

get_mms_upload_session_status — 세션 발송 결과 조회

create_mms_upload_session 이후 업로드/발송 상태를 폴링합니다. uploaded, sendStatus, mseq를 반환합니다.

{ "sessionId": "..." }  // create_mms_upload_session으로 발급받은 sessionId

💰 무료

send_alimtalk — 카카오 알림톡 발송

카카오톡을 통해 알림톡을 발송합니다. 카카오톡 미수신 시 LMS로 자동 대체 발송됩니다.

📋 MCP 공용 템플릿 미리보기

※ 템플릿은 카카오 심사 완료 후 사용 가능합니다. 현재 심사 진행 중.

💰 단가: 15원/건 (failover LMS 대체 발송 시에도 알림톡 단가 15원으로 차감. failover 활성 시 LMS 단가까지 잔액만 확인)

📋 MCP 공용 템플릿 변수 목록

Claude 웹 등 AI 클라이언트에서 템플릿변수를 바로 확인할 수 있도록 정리했습니다. JSON API: GET /api/v1/alimtalk/templates/public

JSON API 제공: GET https://imsend.kr/api/v1/alimtalk/templates/public — Claude 등 AI가 자동으로 읽어 변수명을 확인할 수 있습니다.

send_email_image_upload — 이메일 본문 이미지 업로드

이메일 본문에 삽입할 이미지를 서버에 업로드합니다. 반환된 imageUrl을 send_email의 content에 <img src="..."> 형태로 사용하세요.

// 1단계: 이미지 업로드
{ "imageBody": "Base64값", "imageName": "banner.jpg" }
// 응답
{ "imageUrl": "https://imsend.kr/uploads/email/2026/05/1234_banner.jpg" }

// 2단계: 이메일 본문에 삽입
{
  "to": "user@example.com",
  "subject": "이미지 포함 이메일",
  "content": "<p>본문입니다.</p><img src='https://imsend.kr/uploads/email/...' />"
}

※ 업로드된 이미지는 90일 후 자동 삭제됩니다.

💰 무료

check_balance — 잔여 포인트 조회

현재 잔여 포인트를 조회합니다.

// 파라미터 없음
// 응답 예시
{
  "balance": 4980,
  "unit": "KRW"
}

💰 무료

get_history — 발송 이력 조회

최근 발송 이력을 조회합니다. 실패 건에는 error_code와 error_reason이 포함됩니다.

// 요청
{ "limit": 20 }

// 응답 예시 (성공)
{ "msg_type": "S", "receiver": "01012345678", "status": "DELIVERED", "unit_price": 10 }

// 응답 예시 (실패)
{ "msg_type": "S", "receiver": "01012345678", "status": "FAILED",
  "unit_price": 10, "error_code": "211", "error_reason": "수신거부 또는 번호 오류" }

💰 무료

get_result — 단건 발송 결과 조회

발송 시 반환된 mseq로 실시간 결과(DELIVERED/FAILED/사유)를 조회합니다.

{ "mseq": 19500 }  // send_sms/send_mms/send_alimtalk 발송 시 반환된 값

💰 무료

get_sender — 발신번호 조회

현재 기본 발신번호와 본인인증이 완료된 개인 발신번호(mySenders) 목록을 반환합니다. 파라미터는 없습니다.

// 응답 예시
{ "sender": "033-911-6510", "mySenders": [{ "phone": "01012345678", "verifiedAt": "..." }] }

💰 무료

register_sender_number — 개인 발신번호 등록 (NICE 본인확인)

NICE 본인확인으로 개인 발신번호를 등록합니다. 응답의 authUrl을 사용자에게 안내하고, 인증 완료 후 verify_sender_status로 결과를 확인합니다.

{ "phone": "01012345678" }  // 선택 (NICE 인증 결과와 일치해야 등록)
// 응답: { "sessionId": "...", "authUrl": "...", "expiresIn": ... }

💰 무료

verify_sender_status — 본인확인 상태 조회

register_sender_number 응답의 sessionId로 NICE 본인확인 진행 상태(VERIFIED/PENDING/FAILED/EXPIRED)를 폴링합니다.

{ "sessionId": "..." }  // register_sender_number 응답의 sessionId

💰 무료

charge_point — 포인트 충전

충전용 URL을 반환합니다. 카카오페이 직접 결제는 준비 중이며, 현재는 반환된 충전 페이지(chargeUrl)에서 충전합니다.

{
  "amount": 10000  // 충전 금액 (최소 5,000원)
}

// 응답 (현재)
{
  "note": "카카오페이 충전 준비 중입니다.",
  "amount": 10000,
  "chargeUrl": "https://mcp.imsend.kr/charge?amount=10000"
}

📌 카카오페이 가맹 완료 후 charge_point가 결제 링크를 직접 반환할 예정입니다.