Mobizon MCP Server

MCP server for integrating with the Mobizon Brazil API (mobizon.com.br).

Exposed Tools

• mobizon_get_balance: calls user/getOwnBalance
• mobizon_send_sms: calls message/sendSmsMessage
• mobizon_get_sms_status: calls message/getSMSStatus
• mobizon_list_sms: calls message/list
• mobizon_list_users: calls user/list with pagination and optional criteria filters
• mobizon_list_moderation_campaigns: calls campaign/listglobal for moderation queue
• mobizon_approve_moderation_campaigns: calls campaign/approveglobal with ids
• mobizon_decline_moderation_campaigns: calls campaign/declineglobal with ids and comment (or auto-generated comment)
• mobizon_call: generic call for any API module/method

In mobizon_send_sms, recipient is normalized to BR mobile format: 55 + DDD + 9 + number (example: 5511999999999).

Requirements

• Node.js 20+
• Mobizon API key

Setup

1. Install dependencies:

npm install

1. Configure environment variables (based on .env.example):

• MOBIZON_API_KEY (required)
• MOBIZON_BASE_URL (default: https://api.mobizon.com.br/service)
• MOBIZON_API_VERSION (default: v1)
• MOBIZON_TIMEOUT_MS (default: 30000)

Run Locally

MOBIZON_API_KEY=your_token npm start

MCP Config Example (Claude Desktop / Codex)

{
  "mcpServers": {
    "mobizon": {
      "command": "node",
      "args": ["/path/to/mobizon-mcp/src/index.js"],
      "env": {
        "MOBIZON_API_KEY": "YOUR_TOKEN_HERE",
        "MOBIZON_BASE_URL": "https://api.mobizon.com.br/service",
        "MOBIZON_API_VERSION": "v1",
        "MOBIZON_TIMEOUT_MS": "30000"
      }
    }
  }
}

Notes

• Authentication is done via apiKey in query string, with api=v1 and output=json.
• The server sends application/x-www-form-urlencoded for standard POST calls.
• Some moderation endpoints (approveglobal, declineglobal) use JSON payloads.
• mobizon_call supports GET and POST.
• mobizon_list_users defaults to:
  • withConfig=1
  • withProfile=1
  • withAccessGroup=1
  • withCPRestriction=1
  • withCountryRestriction=1
  • pagination.currentPage=0
  • pagination.pageSize=25
• For search, use either criteria directly or shortcut fields email and number.
• mobizon_list_users also returns (by default) summary.items including:
  • status
  • lastLoginTs
  • balance
  • totalSpending
  • Set includeSummary=false to receive only the raw API payload.

Architecture

• Entrypoint: src/index.js
• Server bootstrap: src/server.js
• Environment config: src/config/env.js
• Mobizon HTTP client: src/core/mobizon-client.js
• Moderation logic: src/moderation/auto-comment.js
• Utilities: src/utils/params.js, src/utils/phone.js, src/utils/mcp.js
• MCP tools (one file per tool): src/tools/

Detailed architecture and extension conventions:

• docs/ARCHITECTURE.md

Reference

• API docs: https://mobizon.com.br/en/help/api-docs