SMS.ir MCP 서버

로컬 Model Context Protocol 서버로, SMS.ir Panel V2 API를 위한 엄선되고 안전하게 게이트된 도구 세트를 제공합니다. Python + FastMCP로 구축되었습니다.

• stdio 전송 방식 (Codex / Claude Desktop / Claude Code용)

• streamable HTTP 전송 방식 (로컬 개발 및 테스트용)

• 읽기 작업은 기본적으로 작동합니다. 모든 전송은 과금되며 기본적으로 차단되어 있으며, 확인 플래그 및 서버 측 킬 스위치 뒤에 있습니다.

• 전화번호, 메시지 텍스트, API 키 및 OTP 코드는 로그에서 마스킹됩니다.

SMS.ir Panel V2 Postman 컬렉션에서 구축되었습니다 (이 저장소에는 포함되지 않음 — 실제 API 키가 포함되어 있습니다). 정규화된 API 설명은 docs/API.md 및 docs/openapi.yaml에 있습니다.

1. 설정

Python 3.10+ 필요 (CPython 3.12에서 개발 및 테스트됨).

cd C:\Users\Kasra\Documents\sms.ir-mcp

# create the project-local virtual environment
py -3.12 -m venv .venv

# install runtime deps (pinned)
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

# ...or install with the package + dev/test extras
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"

Related MCP server: iletiMerkezi MCP Server

2. 구성

모든 구성은 환경 변수에서 가져옵니다. 로컬 사용을 위해 예제 env 파일을 복사하여 채우세요 — git에서 무시되며 커밋되지 않습니다:

copy .env.example .env
notepad .env

실제 환경 변수는 항상 env 파일의 값을 덮어씁니다.

3. 실행

# stdio (what MCP clients launch)
.\.venv\Scripts\python.exe -m sms_ir_mcp --transport stdio

# streamable HTTP for local testing (http://127.0.0.1:8000/mcp)
.\.venv\Scripts\python.exe -m sms_ir_mcp --transport http --host 127.0.0.1 --port 8000

크레딧을 소비하지 않는 빠른 연결 + 인증 확인을 위해 연결된 클라이언트에서 health_check 도구(또는 get_balance)를 호출하세요 — 둘 다 내부적으로 GET /v1/credit입니다.

4. 도구

읽기 전용 도구는 항상 사용할 수 있습니다. 쓰기 도구는 confirm=true 및 SMSIR_ALLOW_SEND=true가 필요합니다; 파괴적 도구는 confirm=true가 필요합니다.

모든 도구는 성공 시 {"ok": true, "data": …, …}를 반환하고 실패 시 {"ok": false, "error": {"code": …, "message": …}}를 반환합니다. 오류 코드: config_error, validation_error, confirmation_required, send_disabled, auth_error, rate_limited, transient_error, api_error, internal_error.

예시

// check balance
get_balance() -> {"ok": true, "data": {"credit": 45210}}

// read the latest OTP received on a given number
extract_latest_otp({"mobile": "9821000"})
  -> {"ok": true, "data": {"otp": "834122", "matched": true, "from": "*****1000", ...}}

// attempt a send without confirming -> refused, nothing sent
send_sms({"message_text": "Hi", "mobiles": ["09121234567"]})
  -> {"ok": false, "error": {"code": "confirmation_required", ...}}

// confirmed send, but kill switch still off -> refused, nothing sent
send_sms({"message_text": "Hi", "mobiles": ["09121234567"], "confirm": true})
  -> {"ok": false, "error": {"code": "send_disabled", ...}}

// edited .env to set SMSIR_ALLOW_SEND=true -> apply it without restarting
reload_config()
  -> {"ok": true, "data": {"config": {"allow_send": true, ...}, "changed": ["allow_send"]}}

// with SMSIR_ALLOW_SEND=true AND confirm=true -> actually sends (billable)
send_sms({"message_text": "Hi", "mobiles": ["09121234567"],
          "line_number": "30007732000000", "confirm": true})
  -> {"ok": true, "data": {"packId": "…", "messageIds": [123], "cost": 1.0}, "recipients": 1}

5. 안전 모델

• 과금 작업 (send_sms, send_verification_code, send_personalized_sms)은 둘 다 필요합니다:

  1. 도구 호출에서 confirm=true, 그리고

  2. 서버 환경에서 SMSIR_ALLOW_SEND=true. 킬 스위치가 꺼져 있으면 확인된 호출도 아무것도 전송하지 않습니다.

• 파괴적 작업 (cancel_scheduled_send)은 confirm=true가 필요합니다.

• 임의의 기본 URL 없음: SMSIR_ALLOW_CUSTOM_BASE_URL=true가 아닌 한 api.sms.ir만 허용됩니다. HTTPS가 강제됩니다.

• 헤더 주입 없음: 호출자는 요청 헤더를 설정할 수 없습니다. 타입이 지정되고 검증된 필드만 전달됩니다.

• 타임아웃 + 제한된 재시도 + 클라이언트 측 속도 제한이 모든 요청에 적용됩니다.

• 마스킹: API 키, 전화번호, 메시지 본문 및 OTP 값은 로그 출력에서 마스킹됩니다.

• 관리 엔드포인트 없음: Postman 컬렉션의 작업만 노출됩니다. 계정/구성 관리를 위한 것은 없습니다.

6. 클라이언트 등록

실제 API 키는 이 폴더의 .env에 넣으세요 — 절대 클라이언트 구성 파일에 넣지 마세요. 아래 각 구성은 클라이언트가 이 서버와 해당 .env를 가리키도록만 합니다.

Codex CLI (설치됨)

codex mcp add sms-ir `
  --env SMSIR_ENV_FILE=C:\Users\Kasra\Documents\sms.ir-mcp\.env `
  -- C:\Users\Kasra\Documents\sms.ir-mcp\.venv\Scripts\python.exe -m sms_ir_mcp --transport stdio

codex mcp list          # sms-ir should appear
codex mcp get sms-ir

수동 동등: docs/codex_config.example.toml.

Claude Code (설치됨)

이 저장소는 프로젝트 범위의 .mcp.json을 제공합니다. 이 디렉토리에서 Claude Code를 열고 프롬프트가 표시되면 sms-ir 서버를 승인하세요:

cd C:\Users\Kasra\Documents\sms.ir-mcp
claude
/mcp                    # shows sms-ir and its tools

대신 사용자 범위로 등록하려면:

claude mcp add sms-ir --scope user `
  --env SMSIR_ENV_FILE=C:\Users\Kasra\Documents\sms.ir-mcp\.env `
  -- C:\Users\Kasra\Documents\sms.ir-mcp\.venv\Scripts\python.exe -m sms_ir_mcp --transport stdio

Claude Desktop (설치되지 않음)

설치된 경우 docs/claude_desktop_config.example.json을 %APPDATA%\Claude\claude_desktop_config.json에 병합하세요 (먼저 백업하고 다른 서버는 유지).

7. 개발

.\.venv\Scripts\python.exe -m ruff check src tests
.\.venv\Scripts\python.exe -m ruff format --check src tests
.\.venv\Scripts\python.exe -m pytest

테스트는 요청 구성, 인증 헤더, 봉투 파싱, 오류 정규화, 재시도/속도 제한, 인수 검증, 마스킹, OTP 추출, 모든 도구에 대한 모의 통합 (Postman 예제 페이로드 사용), OpenAPI-대-컬렉션 일관성, 및 MCP 도구 검색을 다룹니다.

8. 첫 실제 테스트 (자격 증명 제공 후)

이 저장소의 어떤 것도 과금 호출을 하지 않았습니다. 첫 실제 전송을 실행하려면, 명시적으로 승인해야 합니다:

1. .env에 키를 넣으세요:

   SMSIR_API_KEY=<your real key>
   SMSIR_DEFAULT_LINE_NUMBER=<your approved line>
   SMSIR_ALLOW_SEND=true

2. 비용을 들이지 않고 연결을 확인하세요 — 연결된 클라이언트에서 health_check(또는 get_balance)를 호출하세요.

3. 그런 다음, 그때만 첫 과금 호출을 하세요. 정확한 도구 호출:

   send_sms({
     "message_text": "SMS.ir MCP test",
     "mobiles": ["<your own mobile>"],
     "line_number": "<your approved line>",
     "confirm": true
   })

   Codex 표현: "sms-ir 서버의 send_sms 도구를 사용하여 'SMS.ir MCP test'를 <자신의 휴대폰>으로 <라인>에서 confirm true로 보내세요."

9. 문제 해결