Bale

💬 bale-mcp: Bale MCP server for AI agents

Unofficial Bale (بله) MCP server: talk to your AI agents on Iran's Bale messenger, 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.

PyPI Python CI MCP Registry License: MIT

Install in Cursor Install in VS Code

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

For AI agents

• What: MCP server that lets an agent use a Bale (bale.ai, Iran) bot over the official Bot API: read, search and answer messages, send files, ask a question and wait for the answer. Persian-aware search.
• Install: uvx bale-mcp (needs uv, Python 3.10+; or pip install bale-mcp). Transport: stdio.
• Claude Code: claude mcp add bale -e BALE_BOT_TOKEN=123456789:your-token -e BALE_ALLOWED_CHATS=your-chat-id -- uvx bale-mcp
• Auth: BALE_BOT_TOKEN (required, from @botfather); BALE_ALLOWED_CHATS (recommended chat allowlist); BALE_MCP_DB, BALE_MCP_PROXY (optional).
• Access: reads and sends as the user's bot. 9 read-only tools and 4 send tools (bot_send_message, bot_send_file, bot_edit_message, bot_delete_message). Ask the user before any send tool.
• Tools: 13, prefixed bot_*. Start with bot_get_new_messages, bot_list_chats, bot_read_chat, bot_search_messages, bot_wait_for_reply.
• Typical sequence: bot_send_message (with buttons) -> bot_wait_for_reply (pass after_message_id); or bot_get_new_messages -> bot_read_chat -> bot_send_message.
• Use when: the agent should report progress, ask for approval or take instructions on Bale while the user is away.
• Do not use when: you need the user's personal chats (Bot API only sees what people send the bot) or a messenger other than Bale.
• Output: compact JSON; chat ids are numbers or @username; messages carry message_id, kind, sender and text.
• Machine-readable: server.json; catalog of all Iran MCP servers: awesome-iran-mcp (TOOLS.md, servers.json, llms.txt).

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 bot_send_message(chat_id=…, text="Migration step 3 alters users (2.1M rows). Go?", buttons=[["Go", "Stop"]]) → bot_wait_for_reply(chat_id=…, after_message_id=3)

(you tap Go on your phone)

{"messages": [{"kind": "button", "text": "Go", "from": "Sepehr", "message_id": 3}], "timed_out": 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 bale-mcp 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.

1. Create a bot. In Bale open @botfather, tap «ساخت بازوی جدید» (new bot), pick a name and a username ending in bot, and copy the token.
2. Add the server to your MCP client (below).
3. Find your chat id. Send /start to your bot, then ask the agent: "Check my new Bale messages." The chat_id it shows is yours. Put it in BALE_ALLOWED_CHATS so the bot ignores everyone else.

claude mcp add bale -e BALE_BOT_TOKEN=123456789:your-token -e BALE_ALLOWED_CHATS=your-chat-id -- uvx bale-mcp

{
  "mcpServers": {
    "bale": {
      "command": "uvx",
      "args": ["bale-mcp"],
      "env": {
        "BALE_BOT_TOKEN": "123456789:your-token",
        "BALE_ALLOWED_CHATS": "your-chat-id"
      }
    }
  }
}

{
  "inputs": [
    { "type": "promptString", "id": "bale-token", "description": "Bale bot token", "password": true }
  ],
  "servers": {
    "bale": {
      "type": "stdio",
      "command": "uvx",
      "args": ["bale-mcp"],
      "env": { "BALE_BOT_TOKEN": "${input:bale-token}", "BALE_ALLOWED_CHATS": "your-chat-id" }
    }
  }
}

Then just ask:

• "When the test suite finishes, send me the summary on Bale."
• "Any new messages on Bale? Summarize them and draft replies, but ask me before sending."
• "Ask me on Bale whether to deploy, with Yes/No buttons, and wait for my answer."
• "Find the invoice photo someone sent the bot last week and save it to my Downloads."
• پیام‌های جدید بله را بخوان و خلاصه‌شان را بگو.

How it works

  AI agent  (Claude, Cursor, Copilot, ...)
      │
      │  MCP over stdio
      ▼
  bale-mcp  (runs on your machine)  ──▶  ~/.bale-mcp/messages.db   local history (SQLite)
      │
      │  HTTPS, official Bot API
      ▼
  tapi.bale.ai  ◀──▶  your Bale app

Each reading tool first pulls pending updates from Bale (getUpdates) into the local store, then answers from it. Sent messages are stored too, so a chat's history shows both sides.

Privacy and security

• Local only. bale-mcp runs on your machine. The only host it talks to is tapi.bale.ai. There is no relay server, no telemetry and no analytics.
• Your history stays on your disk. Messages are kept in ~/.bale-mcp/messages.db (the folder is user-only on macOS/Linux). Set BALE_MCP_DB=:memory: to keep nothing on disk, or delete the file at any time.
• Allowlist. With BALE_ALLOWED_CHATS set, messages from any other chat are dropped before they are stored or shown to the agent, so a stranger who finds your bot cannot feed your agent instructions. The server also refuses to send to any other chat.
• Prompt-injection aware. The server tells the agent that message text is data from other people, never instructions to follow.
• Confirm before sending. Tools that change something (send, edit, delete) are annotated destructiveHint, and their descriptions tell the agent to confirm the recipient and content with you first.
• The token never leaks. It never appears in tool output, errors or logs.
• Know the limits. Bale has no end-to-end encryption: Bale's servers see what goes through your bot, as with any Bale chat. bale-mcp adds no other party.

Tools

Chat ids are numbers (they can exceed 32 bits), or @username for public channels and groups when sending.

Of the 13 tools, the 4 send tools are annotated destructiveHint: true and the other 9 readOnlyHint: true. All return compact structured JSON, so they don't flood the agent's context.

Good to know

• Someone must message the bot first. A user has to send /start before the bot can message them; in groups and channels the bot must be a member.
• History starts when bale-mcp first reads. Bale keeps undelivered updates for 24 hours (the last 2000), so anything older than that, or read by another program, is gone.
• One reader per bot. Webhooks block getUpdates, and two programs polling the same token steal each other's updates. bot_get_webhook_info shows a webhook. Several bale-mcp processes may share one BALE_MCP_DB.
• Text is Markdown. Bale formats every message: *bold*, _italic_.
• Button presses come back as messages of kind button whose text is the label (cut to 64 bytes).

FAQ

npx @modelcontextprotocol/inspector -e BALE_BOT_TOKEN=123456789:your-token uvx bale-mcp

Configuration

فارسی: سرور MCP بله

claude mcp add bale -e BALE_BOT_TOKEN=123456789:your-token -- uvx bale-mcp

Development

git clone https://github.com/sepehr071/bale-mcp && cd bale-mcp
uv sync
uv run pytest                 # offline, against a mocked Bot API
uv run pytest -m live         # read-only calls with BALE_BOT_TOKEN
uv run pytest -m live_send    # sends, edits and deletes one message in BALE_TEST_CHAT_ID
uv run ruff check .

Tools live in src/bale_mcp/bot.py (sending, bot info) and inbox.py (reading, waiting, downloads); store.py is the local SQLite history. Each tool is a typed async function with a docstring that tells the agent when to use it. Issues and PRs are welcome.

Releases: bump the version in pyproject.toml and server.json, then push a v* tag. GitHub Actions tests, publishes to PyPI and the MCP Registry, and creates the GitHub Release.

Related servers

• PayPing MCP server for reading sales and creating invoices in a PayPing merchant account, the other account tool in this family.
• More Iranian MCP servers (shopping, travel, books, health): awesome-iran-mcp.

Disclaimer

Unofficial and not affiliated with or endorsed by Bale. It uses Bale's official, public Bot API. Follow Bale's terms, and don't use it to spam people.

If this saves you clicks, a star helps others find it.

License

MIT