bale-mcp

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

<div align="center">

<img src="https://raw.githubusercontent.com/sepehr071/bale-mcp/main/.github/banner.png" alt="bale-mcp: unofficial Bale MCP server for Claude, Cursor and Copilot" width="100%">

# 💬 bale-mcp: Bale MCP server for AI agents

**Unofficial Bale (<span dir="rtl">بله</span>) MCP server: talk to your AI agents on Iran's Bale messenger, privately.**<br>
Let Claude, Cursor or Copilot read what people send your Bale bot, keep a searchable history,<br>
reply, send files, and ask you a question and wait for your tap, all from your own machine.

[![PyPI](https://img.shields.io/pypi/v/bale-mcp?color=2563eb)](https://pypi.org/project/bale-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/bale-mcp)](https://pypi.org/project/bale-mcp/)
[![CI](https://github.com/sepehr071/bale-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/sepehr071/bale-mcp/actions/workflows/ci.yml)
[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.sepehr071%2Fbale--mcp-7c3aed)](https://registry.modelcontextprotocol.io/?q=bale-mcp)
[![License: MIT](https://img.shields.io/badge/license-MIT-16a34a)](https://github.com/sepehr071/bale-mcp/blob/main/LICENSE)

[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=bale&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJiYWxlLW1jcCJdLCJlbnYiOnsiQkFMRV9CT1RfVE9LRU4iOiJ5b3VyLWJvdC10b2tlbiIsIkJBTEVfQUxMT1dFRF9DSEFUUyI6InlvdXItY2hhdC1pZCJ9fQ==)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_bale--mcp-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=bale&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22bale-mcp%22%5D%2C%22env%22%3A%7B%22BALE_BOT_TOKEN%22%3A%22your-bot-token%22%2C%22BALE_ALLOWED_CHATS%22%3A%22your-chat-id%22%7D%7D)

[Quick start](#quick-start) · [What it can do](#what-bale-mcp-can-do) · [Privacy](#privacy-and-security) · [Tools](#tools) · [FAQ](#faq) · [فارسی](#فارسی)

</div>

---

## 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](https://docs.astral.sh/uv/getting-started/installation/), 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](server.json); catalog of all Iran MCP servers: [awesome-iran-mcp](https://github.com/sepehr071/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 (بله)](https://bale.ai). 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)*
>
> ```json
> {"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.

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

## 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](https://docs.astral.sh/uv/getting-started/installation/) and a Bale bot.

1. **Create a bot.** In Bale open [@botfather](https://ble.ir/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.

<details open>
<summary><b>Claude Code</b></summary>

```bash
claude mcp add bale -e BALE_BOT_TOKEN=123456789:your-token -e BALE_ALLOWED_CHATS=your-chat-id -- uvx bale-mcp
```
</details>

<details>
<summary><b>Claude Desktop</b></summary>

Settings → Developer → Edit Config, then add:

```json
{
  "mcpServers": {
    "bale": {
      "command": "uvx",
      "args": ["bale-mcp"],
      "env": {
        "BALE_BOT_TOKEN": "123456789:your-token",
        "BALE_ALLOWED_CHATS": "your-chat-id"
      }
    }
  }
}
```
</details>

<details>
<summary><b>Cursor</b></summary>

Click **Install in Cursor** above and fill in the two values, or add the Claude Desktop block to `~/.cursor/mcp.json`.
</details>

<details>
<summary><b>VS Code (Copilot agent mode)</b></summary>

Add to `.vscode/mcp.json`. VS Code asks for the token once and stores it securely:

```json
{
  "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" }
    }
  }
}
```
</details>

<details>
<summary><b>Anything else</b></summary>

It's a standard stdio MCP server: run `uvx bale-mcp`, or `pip install bale-mcp` and run `bale-mcp`, with
`BALE_BOT_TOKEN` in the environment.
</details>

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."
- <span dir="rtl">پیام&zwnj;های جدید بله را بخوان و خلاصه&zwnj;شان را بگو.</span>

## How it works

```text
  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.

<details open>
<summary><b>📥 Read</b> (6)</summary>

| Tool | What it does |
|---|---|
| `bot_get_new_messages` | Messages people sent the bot since the last check, from every chat, oldest first |
| `bot_list_chats` | Chats