kirimi-mcp

MCP server for the Kirimi WhatsApp API. Exposes Kirimi as tools so AI agents can send WhatsApp messages, OTP, broadcasts and official WABA templates.

Works with any MCP client: Claude Desktop, Claude Code, Cursor, and others.

Setup

Kirimi authenticates with a user_code + secret pair sent in the request body. There is no API key and no bearer token. Get both from the Credentials page in the Kirimi dashboard, and your device ID from the device list.

Install

Claude Code

claude mcp add kirimi npx -y kirimi-mcp \
  -e KIRIMI_USER_CODE=YOUR_USER_CODE \
  -e KIRIMI_SECRET=YOUR_SECRET \
  -e KIRIMI_DEVICE_ID=D-XXXXX

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "kirimi": {
      "command": "npx",
      "args": ["-y", "kirimi-mcp"],
      "env": {
        "KIRIMI_USER_CODE": "YOUR_USER_CODE",
        "KIRIMI_SECRET": "YOUR_SECRET",
        "KIRIMI_DEVICE_ID": "D-XXXXX"
      }
    }
  }
}

From source

git clone https://github.com/kiriminow/kirimi-mcp
cd kirimi-mcp
npm install
npm run build

Then point your client at node /path/to/kirimi-mcp/dist/index.js.

Environment variables

| Variable | Required | Description | |----------|----------|-------------| | KIRIMI_USER_CODE | yes | User code from the Credentials page | | KIRIMI_SECRET | yes | Secret from the Credentials page | | KIRIMI_DEVICE_ID | no | Default device for device-scoped tools. Required if you do not pass device_id per call. | | KIRIMI_API_BASE_URL | no | Override the API base URL (default https://api.kirimi.id) | | KIRIMI_TIMEOUT_MS | no | Request timeout, default 30000 |

Tools

Messaging (QR device)

| Tool | Purpose | |------|---------| | send_message | Send text or media to one recipient. The normal way to reply. | | send_message_fast | Same without the typing indicator. Use for time-sensitive messages. | | broadcast_message | Send to up to 1000 recipients. Server enforces a minimum 30s gap. |

OTP

| Tool | Purpose | |------|---------| | send_otp | Send an OTP. method: whatsapp (official provider, Rp 595/delivered), device (own device, free), waba_user (own WABA template, free). | | verify_otp | Check the code the customer entered. |

Devices

| Tool | Purpose | |------|---------| | list_devices | All devices with connection status. | | device_status | Live status of one device. Check before broadcasting. | | device_status_enhanced | Status plus message statistics. | | create_device | Buy a new device with a package. | | connect_device | Start pairing, returns the QR/session state. | | renew_device | Renew a device subscription. |

Contacts

| Tool | Purpose | |------|---------| | save_contact | Save one contact. Existing numbers are skipped. | | save_contacts_bulk | Import up to 1000 contacts. |

Account

| Tool | Purpose | |------|---------| | get_user_info | Name, balance, AI quota, device counts, message stats. | | list_packages | Packages you can buy, with prices. |

WABA (official WhatsApp Business API)

| Tool | Purpose | |------|---------| | send_waba_template | Send a Meta-approved template. Required to start a conversation. | | waba_list_conversations | Numbers still inside the 24h customer service window. | | waba_reply | Free-form reply. Only works inside that 24h window. | | waba_sync_templates | Refresh template approval status from Meta. |

Rules of thumb

• Phone numbers use the country code, no +, no leading zero: 6281234567890.
• Two send paths, not interchangeable. The QR device sends free-form text any time and is the only path that can reach WhatsApp groups. The official WABA path requires an approved template to start a conversation, cannot reach groups, and is addressed by waba_id rather than device_id.
• Free text on WABA only works within 24 hours of the customer's last message. Call waba_list_conversations first.
• Before a broadcast, call device_status and confirm the device is connected. Leave at least 30 seconds between messages.
• A successful WABA response means Meta accepted the message, not that it was delivered. Final status arrives via webhook.
• Always use send_otp for OTP, never send_message.

Development

npm install
npm run build
npm test        # builds, then runs the test suite
bun run dev     # run from source without building

License

MIT