SOLAPI MCP Server

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"
}

환경변수 (Ceiling)

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

Confirm 플래그 (Two-step send)

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

• confirmed=false(기본) → SOLAPI를 호출하지 않고 미리보기만 반환

• confirmed=true → 정책 검증 후 실제 발송

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

동적 정책 조회/변경

도구 카탈로그

문서/예제 (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 버전: