mcp-sms-ir/README.md

MCP Server for SMS.ir messaging services

# SMS.ir MCP Server

This is a Model Context Protocol (MCP) server for SMS.ir messaging services. It allows AI assistants like Claude to send SMS messages via the SMS.ir API.

## Features

- Send single SMS messages to individual recipients
- Send bulk SMS messages to multiple recipients
- Send verification code SMS messages using templates
- Check account credit balance

## Installation

### Prerequisites

- Node.js v18 or newer
- An API key from SMS.ir

### Installation Methods

#### Method 1: Install from npm (Recommended)

You can install the MCP server directly from npm using npx:

```bash
# No installation needed; npx will run it on demand
```

This method is preferred as it allows you to use the server without downloading it manually, and it's easy to update.

#### Method 2: Manual Installation

If you prefer to manually install and customize the server:

1. Clone this repository:
```bash
git clone https://github.com/your-username/mcp-sms-ir.git
cd mcp-sms-ir
```

2. Install dependencies:
```bash
bun install
# or
npm install
```

3. Build the project:
```bash
npm run build
```

4. Optionally, you can publish it locally:
```bash
npm link
```

## Configuration

### Getting an API Key from SMS.ir

1. Create an account on [SMS.ir](https://sms.ir/) if you don't already have one
2. Log in to your account
3. Go to your user panel
4. Find the API Key section and generate/copy your API key

### Configuring the MCP Server in Cline VSCode Extension

Add the SMS.ir server to your Cline MCP settings file:

#### Using npx (Recommended)

```json
{
  "mcpServers": {
    "sms-ir": {
      "command": "npx",
      "args": ["-y", "mcp-sms-ir"],
      "env": {
        "SMS_IR_API_KEY": "your-api-key-from-sms-ir"
      }
    }
  }
}
```

#### Using local installation

```json
{
  "mcpServers": {
    "sms-ir": {
      "command": "node",
      "args": ["/path/to/mcp-sms-ir/build/index.js"],
      "env": {
        "SMS_IR_API_KEY": "your-api-key-from-sms-ir"
      }
    }
  }
}
```

Replace `/path/to/mcp-sms-ir` with the actual path to this repository on your system, and `your-api-key-from-sms-ir` with your actual API key from SMS.ir.

### Configuring the MCP Server in Claude Desktop App

Add the SMS.ir server to your Claude desktop app configuration file:

**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**Linux**: `~/.config/Claude/claude_desktop_config.json`

#### Using npx (Recommended)

```json
{
  "mcpServers": {
    "sms-ir": {
      "command": "npx",
      "args": ["-y", "mcp-sms-ir"],
      "env": {
        "SMS_IR_API_KEY": "your-api-key-from-sms-ir"
      }
    }
  }
}
```

#### Using local installation

```json
{
  "mcpServers": {
    "sms-ir": {
      "command": "node",
      "args": ["/path/to/mcp-sms-ir/build/index.js"],
      "env": {
        "SMS_IR_API_KEY": "your-api-key-from-sms-ir"
      }
    }
  }
}
```

## Publishing to npm

To make this package available via npx, you need to publish it to npm. Here's how:

1. Make sure you have an npm account. If not, create one at [npmjs.com](https://www.npmjs.com/signup).

2. Log in to npm from your terminal:
   ```bash
   npm login
   ```

3. Update the package.json file with your information:
   - Set your name as the author
   - Update the repository URL to point to your GitHub repository
   - Make sure the package name is unique (check on npmjs.com)

4. Prepare your package for publication:
   ```bash
   npm run build
   ```

5. Publish the package:
   ```bash
   npm publish
   ```
   
   If this is your first time publishing this package, use:
   ```bash
   npm publish --access=public
   ```

6. Once published, anyone can use your MCP server by adding it to their MCP settings using npx as shown in the configuration sections above.

## Available Tools

### 1. `send_sms` - Send a Single SMS

Send an SMS message to a single recipient.

**Parameters:**
- `mobile` (required): Recipient mobile number (e.g., "09121234567")
- `message` (required): Message content
- `lineNumber` (optional): Sender line number
- `sendDateTime` (optional): Scheduled date and time for sending the message (ISO format)

**Example:**
```json
{
  "mobile": "09121234567",
  "message": "Hello from SMS.ir MCP!",
  "lineNumber": "3000xxxx"
}
```

### 2. `send_bulk_sms` - Send Bulk SMS

Send the same SMS message to multiple recipients.

**Parameters:**
- `mobiles` (required): Array of recipient mobile numbers
- `messageText` (required): Message content to send to all recipients
- `lineNumber` (optional): Sender line number
- `sendDateTime` (optional): Scheduled date and time for sending the message (ISO format)

**Example:**
```json
{
  "mobiles": ["09121234567", "09123456789"],
  "messageText": "Hello from SMS.ir MCP!",
  "lineNumber": "3000xxxx"
}
```

### 3. `send_verification_code` - Send Verification Code

Send a verification code SMS using a template.

**Parameters:**
- `mobile` (required): Recipient mobile number
- `templateId` (required): Template ID from SMS.ir panel
- `parameters` (required): Array of parameters to substitute in the template

**Example:**
```json
{
  "mobile": "09121234567",
  "templateId": "100000",
  "parameters": [
    {
      "name": "CODE",
      "value": "123456"
    }
  ]
}
```

### 4. `check_credit` - Check Account Credit

Check the remaining credit in your SMS.ir account.

**Parameters:** None

## Usage Examples with Claude

Once the MCP server is properly configured, you can ask Claude to use it:

### Sending a Single SMS

You: "Can you send an SMS to 09121234567 saying 'Hello from Claude'?"

Claude will use the `send_sms` tool to send the message.

### Sending a Verification Code

You: "Send a verification code to 09121234567 using template ID 100000 with code 123456"

Claude will use the `send_verification_code` tool with the template and parameters.

### Checking Account Credit

You: "Check my SMS.ir account credit balance"

Claude will use the `check_credit` tool to retrieve and report your current balance.

## License

MIT

## Acknowledgements

- [SMS.ir](https://sms.ir/) for providing the messaging API
- [Model Context Protocol](https://modelcontextprotocol.io/) for enabling this integration