SOLAPI Server

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

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

빠른 시작

전역 설치 (권장)

Package Manager	Command
npm	npm install -g @solapi/mcp-server
yarn	yarn global add @solapi/mcp-server
pnpm	pnpm add -g @solapi/mcp-server
bun	bun add -g @solapi/mcp-server

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

• 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 인자로 지정할 수 있습니다.

도구	동작
configure_setup	새 프로필 등록 (또는 기존 프로필 덮어쓰기)
configure_list	저장된 프로필 목록
configure_show	프로필 정보 (시크릿은 마스킹)
configure_use	활성 프로필 전환
configure_delete	프로필 삭제

발송 안전 가드

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

활성화 방법

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

MCP 대화 중에 활성화:

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

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

부팅 시부터 활성화

mcp.json의 env에 추가:

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

환경변수 (Ceiling)

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

환경변수	효과
SOLAPI_MCP_DISABLE_SEND=true	Hard lock. MCP 도구로도 발송 활성화 불가.
SOLAPI_MCP_ENABLE_SEND=true	부팅 시 발송 활성화로 시작.
SOLAPI_MCP_MAX_RECIPIENTS=N	한 번의 발송 호출에서 허용되는 최대 수신자 수. 기본 10. MCP에서 더 낮출 수는 있지만 더 높일 수 없음.
SOLAPI_MCP_ALLOWED_SENDERS=01012345678,01087654321	발신번호 화이트리스트. 비우면 무제한.
SOLAPI_MCP_SOLACTL_BIN=/path/to/solactl	자동 다운로드 대신 시스템에 설치된 solactl 사용.
SOLAPI_MCP_AUTO_UPGRADE=true	MCP 서버 부팅 시 GitHub Releases에서 latest로 자동 업그레이드. (기본 off — 패키지가 핀한 버전 사용)

Confirm 플래그 (Two-step send)

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

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

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

동적 정책 조회/변경

도구	동작
get_mcp_policy	현재 정책 + ceiling 반환
update_mcp_policy	sendEnabled / maxRecipients / allowedSenders 변경 (ceiling 위반 거부, 세션 한정)

도구 카탈로그

문서/예제 (read-only, 가드 없음)

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

인증

• configure_setup, configure_list, configure_show, configure_use, configure_delete

조회 (read-only, 가드 없음)

• 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

발송 (confirmed=true 필수)

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

변경 (confirmed=true 필수)

• 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로 부팅마다 자동 수행 가능)

solactl 의존성

내장 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 증가 문제를 일으키며, 핀한 버전은 "패키지가 검증한 조합"을 보장합니다.

Internal SDK version

내장 SDK 버전:

Lang	Version
Node.js	5.5.2
Kotlin(Java)	1.0.3
Python	5.0.2
PHP	5.0.6
Go	2.0.0
ASP	1.0.0