AI integration (MCP)

The GetSMS MCP server gives your AI assistant the tools to send SMS in Morocco, follow their delivery and check your balance. It speaks the Model Context Protocol, understood by Claude, Cursor, VS Code and most agents.

You ask in plain language, the assistant calls the API for you:

Send “Your order #8841 is ready, pick it up before 7 pm” to 06 12 34 56 78, then tell me whether it was delivered.

Install

1. Open API keys in the dashboard and copy your test key sk_test_…. With it nothing is sent and nothing is charged (see Sandbox).

2. Add the server to your client. It needs Node.js 18 or later.

   Claude Code

   claude mcp add getsms --env GETSMS_API_KEY=sk_test_YOUR_KEY -- npx -y @getsms/mcp

   Add --scope user to have it in every project.

   Claude Desktop

   Settings → Developer → Edit Config, then in claude_desktop_config.json:

   {
     "mcpServers": {
       "getsms": {
         "command": "npx",
         "args": ["-y", "@getsms/mcp"],
         "env": { "GETSMS_API_KEY": "sk_test_YOUR_KEY" }
       }
     }
   }

   Restart Claude Desktop.

   Cursor

   In ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

   {
     "mcpServers": {
       "getsms": {
         "command": "npx",
         "args": ["-y", "@getsms/mcp"],
         "env": { "GETSMS_API_KEY": "sk_test_YOUR_KEY" }
       }
     }
   }

   VS Code

   In .vscode/mcp.json. VS Code asks for the key once and stores it securely:

   {
     "inputs": [
       { "type": "promptString", "id": "getsms-key", "description": "GetSMS API key", "password": true }
     ],
     "servers": {
       "getsms": {
         "type": "stdio",
         "command": "npx",
         "args": ["-y", "@getsms/mcp"],
         "env": { "GETSMS_API_KEY": "${input:getsms-key}" }
       }
     }
   }

3. Ask the assistant to send a test SMS to +212600000002: it is delivered, then the simulated recipient replies “OUI” after 9 seconds.

4. When you are happy with it, replace the test key with your live key uk_….

Tools

Tool	What it does	Cost
send_sms	Sends an SMS to a Moroccan mobile (+2126…, +2127…; 06… and 07… are converted). from, request_id and send_at are optional.	Uses your credits
send_bulk_sms	The same text to up to 1,000 recipients, duplicates removed, all or nothing. from is required with a live key.	Uses your credits
get_message	A message and its up-to-date status.	Free
list_messages	A conversation between your number and a contact, replies included.	Free
get_balance	Your balance in dirhams excl. VAT, your price per SMS and how many SMS it covers.	Free
estimate_cost	The segments of a text and its cost for N recipients, computed locally the way GetSMS bills.	Free, no API call
list_phone_numbers	Your sending numbers, usable as from.	Free

Results always say whether the send happened in the sandbox (sandbox: true). The getsms://docs/quickstart resource sums up pricing, statuses and test numbers.

Credits and security

With a live key, the assistant spends your credits

Each segment is charged at your unit price (see Credits and billing). Keep tool confirmation on in your client for send_sms and send_bulk_sms, and ask for an estimate before a large send.

• No double send on a retry. When the assistant passes a request_id, a retry with the same ID returns the first result instead of sending the SMS again: the API guarantees it for 24 h, and the MCP server answers without even calling it again within the same process.
• Errors the assistant can act on. Insufficient credit (402), rejected key (401), invalid parameter (422): the assistant gets a clear message, with cost and balance in dirhams, and can tell you what to do.
• Your key stays with you. It is only sent to api.getsms.tech, in the x-api-key header. It never appears in logs or in the results given to the model.
• The test key is limited. It sends and reads sandbox messages, with no access to the balance or the numbers.

HTTP server

For a hosted agent or a team, run the server over HTTP (Streamable HTTP transport). It keeps no session and no key: every request carries its caller’s key.

npx -y @getsms/mcp --http --port 3333

The endpoint is http://127.0.0.1:3333/mcp. Clients send Authorization: Bearer <your GetSMS key>:

claude mcp add --transport http getsms http://127.0.0.1:3333/mcp \
  --header "Authorization: Bearer sk_test_YOUR_KEY"

By default the server only listens on the local machine. To expose it (--host 0.0.0.0), put it behind an HTTPS proxy and give its public name: the server then refuses any request addressed to another name (DNS rebinding protection).

npx -y @getsms/mcp --http --host 0.0.0.0 --allowed-host mcp.your-domain.com

Environment variables

Variable	Default	Purpose
GETSMS_API_KEY	—	Your key, in stdio mode.
GETSMS_API_URL	https://api.getsms.tech	API URL.
GETSMS_TIMEOUT_MS	30000	Timeout of each call, in milliseconds.