bale-mcp
Advanced tools
Private, local MCP server for Bale (bale.ai) bots: let AI agents read, search and answer messages, ask and wait for replies, and send or download files through the official Bot API.
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 through the official Bot API.
For AI agents · Quick start · What it can do · Privacy · Tools · FAQ · فارسی
tapi.bale.ai: read, search and answer messages, send files, ask a question and wait for the answer. Persian-aware search.uvx bale-mcp (needs uv, Python 3.10+; or pip install bale-mcp). Transport: stdio.claude mcp add bale -e BALE_BOT_TOKEN=123456789:your-token -e BALE_ALLOWED_CHATS=your-chat-id -- uvx bale-mcpBALE_BOT_TOKEN (required, from @botfather); BALE_ALLOWED_CHATS (recommended chat allowlist); BALE_MCP_DB, BALE_MCP_SEND_DIRS, BALE_MCP_PROXY (optional). Never ask the user to paste the token into chat; it belongs in the server's environment.bot_send_message, bot_send_file, bot_edit_message, bot_delete_message; annotated destructiveHint): confirm recipient and content with the user before calling them. 6 reading tools are not destructive but consume Bale updates, mark messages read or save files locally; 3 bot-info tools are read-only.bot_. Start with bot_get_me, then bot_get_new_messages, bot_list_chats, bot_read_chat, bot_search_messages, bot_wait_for_reply.bot_send_message (with buttons) -> bot_wait_for_reply (pass after_message_id); or bot_get_new_messages -> bot_read_chat -> bot_send_message.@username for public chats; dates are ISO 8601 UTC; messages carry message_id, kind, sender and text.TOOLS.md, servers.json, llms.txt).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.
bale-mcp keeps them in a local SQLite fileExample prompts:
You need uv and a Bale bot.
bot, and copy the token./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
Settings → Developer → Edit Config, then add:
{
"mcpServers": {
"bale": {
"command": "uvx",
"args": ["bale-mcp"],
"env": {
"BALE_BOT_TOKEN": "123456789:your-token",
"BALE_ALLOWED_CHATS": "your-chat-id"
}
}
}
}
Click Install in Cursor above and fill in the two values, or add the Claude Desktop block to ~/.cursor/mcp.json (or .cursor/mcp.json in a project).
Click Install in VS Code above, or add to .vscode/mcp.json. This version asks for the token once and stores it securely:
{
"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" }
}
}
}
codex mcp add bale --env BALE_BOT_TOKEN=123456789:your-token --env BALE_ALLOWED_CHATS=your-chat-id -- uvx bale-mcp
Or in ~/.codex/config.toml:
[mcp_servers.bale]
command = "uvx"
args = ["bale-mcp"]
[mcp_servers.bale.env]
BALE_BOT_TOKEN = "123456789:your-token"
BALE_ALLOWED_CHATS = "your-chat-id"
Add the Claude Desktop block (with its env values) to ~/.gemini/settings.json.
Add the Claude Desktop block (with its env values) to ~/.codeium/windsurf/mcp_config.json.
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.
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.~/.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.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.destructiveHint, and
their descriptions tell the agent to confirm the recipient and content with you first.bot_send_file reads local files only from BALE_MCP_SEND_DIRS (by default the
download folder and the working directory); symlinks are resolved first and paths outside are refused.bale-mcp adds no other
party.Chat ids are numbers (they can exceed 32 bits), or @username for public channels and groups when sending.
| 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 the bot has talked in, with unread count and last message |
bot_read_chat | A chat's recent history in both directions |
bot_search_messages | Search the stored history; Persian-aware |
bot_wait_for_reply | Wait until someone writes in a chat or taps a button (up to 10 minutes) |
bot_download_file | Save a photo, document, voice note, ... to this computer (max 20 MB; never overwrites) |
| Tool | What it does |
|---|---|
bot_send_message | Send text, optionally as a reply and with inline buttons |
bot_send_file | Send a photo, document, video, audio or voice file by URL or local path (max 50 MB; local files only from BALE_MCP_SEND_DIRS) |
bot_edit_message | Replace the text of a message the bot sent |
bot_delete_message | Delete a message |
| Tool | What it does |
|---|---|
bot_get_me | Check the token: bot id, username, name |
bot_get_chat | A chat's type, title or name, username and description |
bot_get_webhook_info | Whether a webhook is set, pending updates and the last error |
Of the 13 tools, the 4 send tools are annotated destructiveHint: true, the 3 bot tools readOnlyHint: true, and
the 6 reading tools are neither read-only nor destructive (they advance Bale's update offset, mark messages read or
write a file). All return compact JSON, so they don't flood the agent's context.
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. The server uses one HTTP client that
ignores system proxy variables, does not retry failed calls and keeps no response caches. Every reply is one
compact JSON block.
/start before the bot can message them; in groups and
channels the bot must be a member.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.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.limit;
bot_search_messages cuts each text to max_chars (default 500).bot_download_file streams the file and aborts past that size.bot_list_chats,
bot_read_chat and bot_search_messages still answer from the local store and add a sync_error note.*bold*, _italic_.bot_edit_message gives back
an empty-looking result; the edit itself works.bot_wait_for_reply uses after_message_id to ignore older messages.button whose text is the label (cut to 64 bytes).BALE_MCP_PROXY if you need one.Yes, this one. It is unofficial and uses Bale's public Bot API with your own bot token. Install it with
uvx bale-mcp and add it to your MCP client as shown in Quick start.
It is free (MIT) and runs on your machine; the only host it talks to is tapi.bale.ai. Set BALE_ALLOWED_CHATS
so strangers who find your bot cannot reach your agent. See Privacy.
No. It uses the official Bot API, so it only sees what people send to your bot, and messages in groups and channels the bot is a member of. It cannot log in as you.
The send tools are marked destructive and their descriptions tell the agent to confirm the recipient and text with
you first, but your MCP client decides how strictly that is enforced. With BALE_ALLOWED_CHATS set, the bot can only
write to the chats you listed.
No: in testing tapi.bale.ai answered without an Iranian IP. If every call fails with "Could not reach
tapi.bale.ai", set BALE_MCP_PROXY to an HTTP proxy that can reach it. Normal system proxy variables are ignored on purpose.
The token is wrong or was revoked. Copy it again from @botfather. (Bale answers a bad token with HTTP 403 or 404.)
bot_wait_for_reply returns timed_out: true when nobody answered in time; the agent can call it again. Some MCP
clients cancel tool calls after about a minute; use a shorter timeout_seconds there.
Run bot_get_webhook_info. If a webhook is set, Bale will not hand out updates to polling, so remove the webhook.
Also check that no other program polls the same bot token, and remember Bale only keeps updates for 24 hours.
uvx is not foundUse the full path to uvx (where uvx on Windows, which uvx on macOS/Linux) as command.
npx @modelcontextprotocol/inspector -e BALE_BOT_TOKEN=123456789:your-token uvx bale-mcp
| Variable | Default | Meaning |
|---|---|---|
BALE_BOT_TOKEN | required | Bot token from @botfather |
BALE_ALLOWED_CHATS | unset (all chats) | Comma-separated chat ids or @usernames; all other chats are ignored and never messaged |
BALE_MCP_DB | ~/.bale-mcp/messages.db | Local history file; :memory: keeps nothing on disk |
BALE_MCP_SEND_DIRS | ~/.bale-mcp/files and the working directory | Folders (separated by ; on Windows, : elsewhere) bot_send_file may upload local files from; symlinks are resolved, paths outside are refused |
BALE_MCP_PROXY | unset | HTTP proxy for every request, e.g. http://user:pass@host:port |
bale-mcp یک سرور MCP غیررسمی برای پیامرسان بله (bale.ai) در ایران است و به دستیار هوش مصنوعی شما (Claude، Cursor، Copilot و ...) اجازه میدهد از طریق بازوی (ربات) بله خودتان پیامها را بخواند، در آنها جستجو کند، پاسخ و فایل بفرستد، و از شما سؤال بپرسد و منتظر جوابتان بماند. از API رسمی بازوهای بله استفاده میکند.
BALE_MCP_DB=:memory: یعنی هیچ ذخیرهای).BALE_ALLOWED_CHATS فقط چتهای شما خوانده میشوند و پیام غریبهها اصلاً به دستیار نمیرسد.جستجوهای رایج: ربات بله، بازوی بله، بات بله، API بله، هوش مصنوعی در بله، اتصال Claude به بله، پیامرسان بله.
نصب در Claude Code: توکن را از @botfather بگیرید و:
claude mcp add bale -e BALE_BOT_TOKEN=123456789:your-token -- uvx bale-mcp
بعد به بازوی خود /start بفرستید و بپرسید: «پیامهای جدید بله را بخوان.» برای نصب در Claude Desktop، Cursor و بقیه برنامهها همان تنظیم بخش Quick start را بگذارید.
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.
Unofficial and not affiliated with or endorsed by Bale. It uses Bale's official, public Bot API. It acts through your own bot and can send, edit and delete messages, so use it with care. Follow Bale's terms, and don't use it to spam people.
If this saves you clicks, a star helps others find it.
FAQs
Private, local MCP server for Bale (bale.ai) bots: let AI agents read, search and answer messages, ask and wait for replies, and send or download files through the official Bot API.
We found that bale-mcp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Security News
The PHP Foundation says Chainguard broke a security embargo ahead of critical RCE patches, as leaks disrupted the coordinated release.
Security News
PHP releases emergency patches for two critical RCE vulnerabilities as agencies urge organizations to take unpatched sites offline.
Threat Research
/Security News
A supply chain attack compromised LiteLLM 1.107.0 on PyPI and Docker, spreading malware that steals cloud credentials, developer secrets, and AI provider keys.