Bale Bot MCP server

<!-- mcp-name: io.github.sepehr071/bale-mcp -->

💬 bale-mcp

Talk to your AI agents on Bale, privately. Let Claude, Cursor or Copilot read what people send your Bale bot, keep a searchable history, reply, send files, and ask you a question and wait for your tap, all from your own machine.

Quick start · What it can do · Privacy · Tools · FAQ · فارسی

Why

Agents now run for minutes or hours: deploys, data jobs, research. You want them to tell you when they are done, ask before they do something risky, and take new instructions while you are away from the keyboard. For many people in Iran that phone is running Bale (بله). With bale-mcp the agent does it through your own Bale bot:

You: Run the migration on staging, but ask me on Bale before you touch the users table.

Agent: calls botsendmessage(chatid=…, text="Migration step 3 alters users (2.1M rows). Go?", buttons=[["Go", "Stop"]]) → botwaitforreply(chatid=…, aftermessage_id=3)

(you tap Go on your phone)

json

{"messages": [{"kind": "button", "text": "Go", "from": "Sepehr", "messageid": 3}], "timedout": false}

Agent: Got your approval. Running step 3 now; I'll message you when it's done.

The tool calls are real; the reply shape is from a live test against tapi.bale.ai on 2026-10-03.

What it can do

• 📥 Read what people send your bot, from every chat, with sender, kind and chat id
• 🗂️ Keep a history: the Bot API forgets messages after 24 hours; bale-mcp keeps them in a local SQLite file
• 🔎 Search that history, Persian-aware: Arabic and Persian ی/ک, Persian and Latin digits and ZWNJ all match
• 🙋 Ask and wait: send a question with inline buttons, then block until you answer or tap
• 📤 Send text (Markdown), photos, documents, video, audio and voice; edit and delete the bot's messages
• 📎 Download files people send (receipts, voice notes, documents) to your computer
• 🔒 Private by design: runs on your machine, talks only to Bale, no telemetry, optional chat allowlist

Quick start

You need uv and a Bale bot.

Shortened. The full README is on GitHub.