Skip to main content
Glama
MojaWave MCP

MojaWave MCP

Official
by mojawave

mojawave-mcp

MojaWave MCP server — connect any MCP-compatible AI assistant to the MojaWave SMS and Email API.

Works with Claude (Desktop & Code), ChatGPT (via OpenAI Agents SDK), Gemini (via Google ADK), Cursor, Windsurf, and any other tool that speaks the Model Context Protocol.

Every tool maps to a documented endpoint of the MojaWave public API — nothing undocumented is exposed.


Available tools

SMS

Tool

API endpoint

What it does

list_sms_sender_ids

GET /sms/sender-ids/approved

List approved sender IDs available on your account — call this before sending to pick the right sender_id

send_sms

POST /sms/send

Send a single SMS, optionally scheduled (schedule_at)

send_bulk_sms

POST /sms/bulk

Start an async bulk SMS job for up to 10,000 recipients — returns a job_id

get_bulk_sms_job

GET /sms/bulk/{id}

Poll the status and progress of a bulk SMS job

Email

Tool

API endpoint

What it does

list_email_domains

GET /email/domains

List sending domains and their verification status — call before sending to confirm a domain is verified

list_email_senders

GET /email/senders

List registered sender addresses available as from_email

send_email

POST /email/send

Send a transactional email — supports HTML + plain text, CC/BCC, reply-to, attachments, scheduled delivery, and tags

Messages & account

Tool

API endpoint

What it does

get_message

GET /messages/{id}

Get full details and delivery timeline for a single message

get_credit_balance

GET /credits

Check current SMS and email credit balances

verify_webhook_signature

—

Verify a webhook's X-MojaWave-Signature (HMAC-SHA256)

Inputs are validated before any request is made (E.164 phone numbers, 1–11-char sender IDs, message length, recipient count, ISO-8601 schedule times, email addresses, subject length), and the client retries 429/5xx responses with backoff that honours Retry-After.


Related MCP server: Twilio SMS Server

Sending SMS

1. list_sms_sender_ids()
   → [{ "sender_id": "MYAPP", "status": "approved" }]

2. send_sms(to="+255712345678", message="Hello!", sender_id="MYAPP")
   → { "id": "...", "status": "sent" }

Sending email

1. list_email_domains()    — confirm your domain is "verified"
2. list_email_senders()    — pick a valid from_email address
3. send_email(to="customer@example.com", from_email="noreply@yourdomain.com",
              subject="Hello", body="Hi there")
   → { "id": "...", "status": "queued" }

Bulk SMS

1. list_sms_sender_ids()   — pick an approved sender ID

2. send_bulk_sms(recipients=["+255700000001", ...], message="...", sender_id="MYAPP")
   → { "job_id": "ec0fb57c-...", "status": "scheduled", "total_recipients": 500 }

3. get_bulk_sms_job(job_id="ec0fb57c-...")
   → { "status": "completed", "total_recipients": 500, "total_credits_cost": 500 }

Installation

pip install mojawave-mcp

Or for local development:

git clone https://github.com/mojawave/mojawave-mcp
cd mojawave-mcp
pip install -e ".[dev]"

Configuration

Copy .env.example to .env and add your API key:

cp .env.example .env
MOJAWAVE_API_KEY=sk_live_mw_xxxxxxxxxxxxxxxxxxxx

Get your API key from the MojaWave dashboard under Settings → API Keys.

Use a test key (sk_test_mw_…) during development — it returns synthetic responses without sending real messages or charging credits.


Connecting to AI assistants

Claude Desktop

Add this block to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "mojawave": {
      "command": "mojawave-mcp",
      "env": {
        "MOJAWAVE_API_KEY": "sk_live_mw_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Restart Claude Desktop. You will see a MojaWave tool icon in the chat interface.


Claude Code (CLI)

claude mcp add mojawave -- env MOJAWAVE_API_KEY=sk_live_mw_xxx mojawave-mcp

Cursor / Windsurf / any stdio MCP client

Point the client at the mojawave-mcp command with your API key as an environment variable. Most clients use the same JSON config format as Claude Desktop above — refer to your client's MCP documentation.


OpenAI Agents SDK (ChatGPT / GPT-4o)

Start the server in SSE mode so OpenAI can reach it over HTTP:

MOJAWAVE_API_KEY=sk_live_mw_xxx mojawave-mcp --transport sse --port 8080

Then connect from Python:

from agents import Agent, Runner
from agents.mcp import MCPServerSse

async def main():
    server = MCPServerSse(url="http://localhost:8080/sse")
    async with server:
        agent = Agent(
            name="MojaWave Agent",
            model="gpt-4o",
            mcp_servers=[server],
        )
        result = await Runner.run(
            agent, "Send an SMS to +255712345678 saying Hello from AI"
        )
        print(result.final_output)

Google Gemini (Google ADK)

Start the server in SSE mode:

MOJAWAVE_API_KEY=sk_live_mw_xxx mojawave-mcp --transport sse --port 8080

Then connect from Python:

from google.adk.agents import LlmAgent
from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset, SseServerParams

mojawave_tools = MCPToolset(
    connection_params=SseServerParams(url="http://localhost:8080/sse")
)

agent = LlmAgent(
    model="gemini-2.0-flash",
    name="mojawave_agent",
    instruction="You can send SMS and email and check credits via MojaWave.",
    tools=[mojawave_tools],
)

Hosted deployment (Docker)

For production, run the SSE server behind a reverse proxy:

FROM python:3.12-slim
RUN pip install mojawave-mcp
ENV MOJAWAVE_API_KEY=""
EXPOSE 8080
CMD ["mojawave-mcp", "--transport", "sse", "--port", "8080"]
docker build -t mojawave-mcp .
docker run -e MOJAWAVE_API_KEY=sk_live_mw_xxx -p 8080:8080 mojawave-mcp

Running locally (stdio)

MOJAWAVE_API_KEY=sk_live_mw_xxx mojawave-mcp

The server reads JSON-RPC from stdin and writes to stdout — the standard MCP stdio transport used by Claude Desktop and most IDE extensions.


Security notes

  • Never commit your API key. Use environment variables or a secrets manager.

  • Use test keys (sk_test_mw_…) in CI/CD and development — no real messages are sent and no credits are charged.

  • Scope API keys to only the permissions they need from the MojaWave dashboard.

  • The AI is instructed to always confirm recipient, content, and sender with you before calling send_sms, send_bulk_sms, or send_email — these spend real credits and deliver real messages.

  • Webhook payloads are signed with X-MojaWave-Signature (HMAC-SHA256) — verify signatures on your server before trusting delivery events.


License

MIT

Available Tools

10 tools
get_bulk_sms_jobA

Get the status and progress of a bulk SMS job.

Args: job_id: The job UUID returned by send_bulk_sms.

Inputs: job_id (required). Returns: result

get_credit_balanceA

Get current SMS and email credit balances for your organization.

Inputs: no named parameters. Returns: result

get_messageA

Get full details and delivery status (timeline) for a single message.

Args: message_id: The UUID of the message returned when it was sent.

Inputs: message_id (required). Returns: result

list_email_domainsA

List all email sending domains registered on your account.

Call this before send_email to confirm which domains are verified and available. Only domains with status "verified" can send mail.

Inputs: no named parameters. Returns: result

list_email_sendersA

List all registered sender addresses available for sending email.

Returns the email addresses you can use in the from_email field of send_email. Each sender belongs to a verified domain.

Inputs: no named parameters. Returns: result

list_sms_sender_idsA

List approved SMS sender IDs available on your account.

Returns IDs with status "approved". If the list is empty, the user has no custom sender IDs yet — use 'MojaWave' as the default shared sender ID, which is always available as a fallback. Call this before sending to pick the correct sender ID.

Inputs: no named parameters. Returns: result

send_bulk_smsA

Send the same SMS to up to 10,000 recipients. Processed asynchronously — returns a job_id immediately; use get_bulk_sms_job to track progress.

Confirm the recipient list size, message, and sender_id with the user first — this spends real credits.

Args: recipients: List of phone numbers in E.164 format (1-10,000). message: SMS text content (max 1600 characters). sender_id: Sender ID (1-11 alphanumeric chars). Use list_sms_sender_ids to find approved IDs, or 'MojaWave' as the default fallback. name: Optional campaign name for your reference (e.g. "June Promo").

Inputs: message (required), sender_id (required), recipients (required), name. Returns: result

send_emailA

Send a transactional email from a registered sender address.

Costs 1 credit per recipient (to + each cc + each bcc). At least one of body (plain text) or html is required.

Call list_email_senders first to confirm from_email is registered. ALWAYS confirm to, subject, from_email, and body/html with the user before sending — this spends real credits and delivers a real email.

Args: to: Recipient email address (e.g. customer@example.com). from_email: Registered sender address on a verified domain (e.g. noreply@yourdomain.com). Use list_email_senders to find valid values. subject: Email subject line (max 500 chars). body: Plain-text body. At least one of body or html is required. html: Optional HTML body (e.g. "Hello"). Provide alongside body as a fallback for clients that don't render HTML. from_name: Optional display name shown in the recipient's inbox (e.g. "Duka Masta Billing"). cc: Optional list of CC addresses. Each costs 1 credit. bcc: Optional list of BCC addresses. Each costs 1 credit. reply_to: Optional reply-to address if different from from_email. schedule_at: Optional future delivery time in ISO-8601 (e.g. 2026-06-15T09:00:00Z). Naive datetimes (no Z/offset) are treated as EAT (Africa/Dar_es_Salaam, UTC+3). Leave empty to send immediately. tags: Optional string labels for filtering in message history (max 10).

Inputs: to (required), subject (required), from_email (required), cc, +7 more. Returns: result

send_smsA

Send a single SMS message, optionally scheduled for future delivery.

Confirm recipient, message, and sender_id with the user first — this spends real credits.

Args: to: Recipient phone number in E.164 format (e.g. +255712345678). message: SMS text content (max 1600 characters). sender_id: Sender ID shown to the recipient (1-11 alphanumeric chars, e.g. MYAPP). Use list_sms_sender_ids to find approved IDs. If none exist, use 'MojaWave' as the default shared sender ID. schedule_at: Optional future delivery time in ISO-8601 UTC (e.g. 2026-06-15T09:00:00Z). Leave empty to send immediately.

Inputs: to (required), message (required), sender_id (required), schedule_at. Returns: result

verify_webhook_signatureA

Verify a MojaWave webhook's HMAC-SHA256 signature.

Pass the RAW request body (exactly as received), the value of the X-MojaWave-Signature header, and your webhook signing secret. Returns whether the signature is valid — only act on webhook events that verify as valid.

Args: payload: The raw webhook request body (do not re-serialize it). signature: The X-MojaWave-Signature header value. secret: Your webhook signing secret (whsec_...).

Inputs: secret (required), payload (required), signature (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 10 tools

    Disambiguation5/5

    Each tool covers a distinct operation: sending SMS/email (single and bulk), listing resources, checking status, and verifying webhooks. There is no overlap; even the two 'send' tools are clearly differentiated by single vs. bulk, and each 'list' tool targets a specific resource type.

    Naming Consistency4/5

    All tools use a consistent verb_noun pattern in snake_case (get_, list_, send_, verify_). There is a minor inconsistency: 'list_sms_sender_ids' uses 'sender_ids' while the email counterparts use 'senders' (list_email_senders). The deviation is small but slightly breaks the pattern.

    Tool Count5/5

    10 tools is a well-scoped set for a messaging API. It covers essential operations (sending, listing, status, credit, webhook) without being overwhelming. The count falls comfortably within the ideal 3-15 range.

    Completeness3/5

    The server covers basic send, status, and listing operations but lacks several expected capabilities: no bulk email sending, no way to list sent messages or search history, no update/delete for resources like sender IDs or domains, and no cancellation of scheduled messages. These gaps are notable for a full messaging lifecycle.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables AI assistants and MCP-compatible clients to send and manage SMS messages through the 46elks API, leveraging Swedish telecommunications infrastructure.
      6
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Enables AI assistants to send SMS messages via Twilio through the Model Context Protocol or a standalone REST API. It supports standard messaging, automated greetings, and creative content generation using natural language.
      1
      19 npm
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables any MCP-compatible AI agent to send WhatsApp messages, SMS, OTP codes, and email through a single REST API.
      18
      MIT