SOLAPI 문서/예제 검색과 실제 메시지 발송·관리를 한 번에 제공하는 MCP(Model Context Protocol) 서버입니다. Claude Desktop, Cursor 등에서 사용할 수 있습니다.

내부적으로 solactl CLI를 호출합니다. solactl 바이너리는 설치 시 자동으로 다운로드됩니다 (실패 시 첫 실행 시 재시도).

설치 후 자동으로 다음 작업이 수행됩니다.

• solactl 바이너리 자동 다운로드 (플랫폼별 prebuilt)
• Claude Desktop / Cursor 설정 파일에 MCP 서버 등록

설치 후 Claude Desktop이나 Cursor를 재시작하면 사용 가능합니다.

~/.cursor/mcp.json 또는 Claude Desktop의 claude_desktop_config.json:

{
 "mcpServers": {
 "solapi": {
 "command": "npx",
 "args": ["--latest", "-y", "@solapi/mcp-server"],
 "env": {}
 }
 }
}

MCP 도구로 직접 SOLAPI 자격 증명을 등록할 수 있습니다.

"내 솔라피 키 등록해줘. apiKey는 NCS..., apiSecret은 ..., 프로필 이름은 prod"

→ MCP가 configure_setup 도구를 호출하여 ~/.solactl/credentials.json에 저장합니다.

여러 프로필을 두고 발송 시마다 profile 인자로 지정할 수 있습니다.

발송 도구는 기본적으로 비활성화되어 있습니다. 실수로 메시지가 나가는 것을 막기 위함입니다.

일시적 활성화 (세션 한정)

MCP 대화 중에 활성화:

"발송 활성화해줘" → MCP가 update_mcp_policy({sendEnabled: true}) 호출

MCP 서버 재시작 시 다시 비활성화로 돌아갑니다.

부팅 시부터 활성화

mcp.json의 env에 추가:

"env": {
 "SOLAPI_MCP_ENABLE_SEND": "true"
}

환경변수로 설정한 한계는 MCP 도구로 풀 수 없습니다 (ceiling 역할).

모든 발송 도구는 confirmed: boolean 인자를 갖습니다.

• confirmed=false(기본) → SOLAPI를 호출하지 않고 미리보기만 반환
• confirmed=true → 정책 검증 후 실제 발송

LLM이 사용자 동의 없이 한 번에 발송하는 사고를 막습니다. 카카오 템플릿 변경, 발신번호 삭제 등 변경 도구도 같은 가드를 사용합니다.

• list_examples — SDK 예제 카탈로그
• get_example — 예제 풀 소스
• overview — 개요
• web_search — 문서 검색

• configure_setup, configure_list, configure_show, configure_use, configure_delete

• get_balance — 잔액·포인트
• list_messages — 발송 내역
• list_senderids — 발신번호 목록
• get_quota, list_quota_requests — 발송 한도
• list_kakao_channels, get_kakao_channel, list_kakao_channel_categories
• list_kakao_channel_groups, get_kakao_channel_group
• list_kakao_templates, get_kakao_template, list_kakao_template_categories, get_kakao_template_sendable
• list_kakao_brand_templates, get_kakao_brand_template_sendable

• send_sms, send_lms, send_mms, send_rcs, send_ata, send_bms

• delete_senderid, update_senderid
• request_quota
• create_kakao_template, update_kakao_template, delete_kakao_template
• inspect_kakao_template, cancel_inspect_kakao_template, release_dormant_kakao_template
• create_kakao_brand_template, update_kakao_brand_template, delete_kakao_brand_template

• get_mcp_policy, update_mcp_policy

• upgrade_solactl — solactl을 latest 또는 지정 버전으로 업그레이드 (SOLAPI_MCP_AUTO_UPGRADE=true로 부팅마다 자동 수행 가능)

내장 SDK 예제 외에 발송·조회 기능은 solactl 바이너리에 의존합니다. 본 패키지는 다음 버전을 자동 다운로드합니다:

• solactl v0.1.6 (Linux/macOS amd64·arm64, Windows amd64·arm64)
• 다운로드 위치: <package>/bin/solactl (또는 solactl.exe)
• sha256 검증 후 설치

자동 다운로드가 차단된 환경(CI 등)에서는 SOLAPI_MCP_SOLACTL_BIN=/path/to/solactl로 시스템에 설치된 바이너리를 가리키도록 할 수 있습니다.

기본적으로 패키지가 핀한 버전(v0.1.6)을 사용합니다. 신버전을 사용하려면:

• 수시로 (대화 중): upgrade_solactl 도구를 호출. "solactl 업그레이드해줘" 한 마디로 가능. 특정 버전을 지정하려면 targetVersion: "0.1.7".
• 부팅마다 자동: SOLAPI_MCP_AUTO_UPGRADE=true 환경변수.

기본값을 "수동"으로 둔 이유: 매 호출마다 자동 업그레이드는 GitHub API rate limit 소진과 도구 호출 latency 증가 문제를 일으키며, 핀한 버전은 "패키지가 검증한 조합"을 보장합니다.

내장 SDK 버전: