Skip to main content
Glama
deenesjakoruzh
ali-toghiani

SMS.ir MCP server

by ali-toghiani
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

SMS.ir MCP 服务器

一个本地 Model Context Protocol 服务器， 为 SMS.ir Panel V2 API 提供一组经过筛选、带安全门控的工具。 使用 Python + FastMCP 构建。

  • 面向 Codex / Claude Desktop / Claude Code 的 stdio 传输

  • 面向本地开发与测试的 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

变量

是否必需

默认值

用途

SMSIR_API_KEY

是

–

SMS.ir Panel API 密钥，作为 X-API-KEY 请求头发送

SMSIR_DEFAULT_LINE_NUMBER

否

–

发送工具的备用发送线路

SMSIR_ALLOW_SEND

否

false

总开关。 必须为 true 才能让任何真实发送离开进程

SMSIR_BASE_URL

否

https://api.sms.ir

API 基础 URL（主机已加入白名单）

SMSIR_ALLOW_CUSTOM_BASE_URL

否

false

允许非 api.sms.ir 主机（仅限本地模拟）

SMSIR_TIMEOUT_SECONDS

否

15

每次请求的超时时间

SMSIR_MAX_RETRIES

否

2

瞬时故障（429 / 5xx / 网络）的重试次数

SMSIR_RATE_LIMIT_PER_MINUTE

否

60

客户端速率限制

SMSIR_MAX_PAGE_SIZE

否

200

page_size 接受的上限

SMSIR_LOG_LEVEL

否

INFO

DEBUG / INFO / WARNING / ERROR

SMSIR_ENV_FILE

否

./.env

要自动加载的 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。

工具

类型

API

描述

get_balance

读取

GET /v1/credit

剩余短信额度

list_lines

读取

GET /v1/line

发送线路号码 / 虚拟号码

get_message_report

读取

GET /v1/send/{id}

单条已发送消息的投递报告/状态

get_pack_report

读取

GET /v1/send/pack/{packId}

批量发送包中每个收件人的结果（分页）

list_sent_messages

读取

GET /v1/send/live · /archive

已发送消息，scope=today|archive

list_sent_packs

读取

GET /v1/send/pack · /archive/pack

批量发送包，scope=today|archive

list_inbound_messages

读取

GET /v1/receive/latest · /live · /archive

入站消息，scope=latest|today|archive

extract_latest_otp

读取

GET /v1/receive/latest

包含可解析一次性验证码的最新入站消息（启发式）

health_check

读取

GET /v1/credit

可达性 + 认证检查，永不计费；同时返回生效配置

reload_config

管理

–

无需重启服务器即可重新读取 .env / 环境变量（例如切换 SMSIR_ALLOW_SEND 后）；不发送任何内容

send_sms

计费

POST /v1/send/bulk

向一个或多个收件人发送一条短信

send_verification_code

计费

POST /v1/send/verify

模板化 OTP/验证消息

send_personalized_sms

计费

POST /v1/send/likeToLike

为每个收件人发送不同的短信

cancel_scheduled_send

破坏性

DELETE /v1/send/scheduled/{packId}

取消尚未发送的定时发送包

每个工具在成功时返回 {"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. 故障排查

症状

原因 / 修复

config_error: SMSIR_API_KEY is not set

环境或 .env 中没有密钥；检查客户端传入的 SMSIR_ENV_FILE 路径

每次调用都出现 auth_error

密钥错误/已轮换，或密钥没有 Panel API 访问权限

send_disabled

服务器环境中 SMSIR_ALLOW_SEND 不是 true

修改了 .env 但没有任何变化

服务器在启动时只读取一次配置。调用 reload_config，或重启 MCP 客户端以重新生成服务器

confirmation_required

使用 "confirm": true 重新调用该工具

validation_error: Invalid mobile number

使用 10–15 位数字，可选前导 +

rate_limited

客户端限流器触发；提高 SMSIR_RATE_LIMIT_PER_MINUTE 或放慢速度

transient_error

重试后仍出现网络/5xx 错误；检查连接和 SMS.ir 状态

客户端不显示任何工具

客户端配置中的 command 路径错误；指向 .venv\Scripts\python.exe

出现带 api_status 的 api_error

SMS.ir 拒绝了请求；message 中带有其拒绝原因

This server cannot be installed

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • SendGrid MCP Server

    deyikong
    A
    license
    B
    quality
    A
    maintenance
    Enables comprehensive email marketing and transactional email operations through SendGrid's API v3. Supports contact management, campaign creation, email automation, list management, and email sending with built-in read-only safety mode.
    58
    1,384
    3
    ISC
  • SOLAPI MCP Server by solapi

    SOLAPI MCP Serverofficial

    solapi
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables searching SOLAPI documentation and examples, and sending/managing SMS, LMS, MMS, RCS, and Kakao messages with safety guards.
    250
    MIT

  • instantly-mcp

    katekruger
    A
    license
    A
    quality
    A
    maintenance
    Enables MCP clients to read Instantly.ai analytics and manage leads, campaigns, Unibox, sender accounts, blocklist, and webhooks, with write actions gated behind confirm prompts and configurable safety policies.
    40
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ali-toghiani/sms-ir-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server