bale-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| BALE_MCP_DB | No | Local history file. Default is ~/.bale-mcp/messages.db. Use :memory: to keep nothing on disk. | ~/.bale-mcp/messages.db |
| BALE_BOT_TOKEN | Yes | Bot token from @botfather (required) | |
| BALE_MCP_PROXY | No | HTTP proxy for every request, e.g. http://user:pass@host:port. Default is unset. | |
| BALE_ALLOWED_CHATS | No | Comma-separated chat ids or @usernames; all other chats are ignored and never messaged. Default is unset (all chats). |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| bot_get_meA | Check BALE_BOT_TOKEN and show the bot's id, username and name. |
| bot_get_chatB | Get a chat's type, title or name, username and description. |
| bot_get_webhook_infoA | Show whether a webhook is set (url empty = the reading tools work), pending updates and the last error. |
| bot_send_messageA | Send a real text message from the bot. Confirm recipient and text with the user first. Text is Markdown (bold, italic). The user must have sent the bot /start first (or the bot is in the group/channel). To ask a question, send it (buttons for fixed choices), then call bot_wait_for_reply with the returned message_id. |
| bot_send_fileA | Send a real photo, document, video, audio or voice file from the bot. Confirm recipient and file with the user first. Local paths must lie inside BALE_MCP_SEND_DIRS (default: the download folder only). |
| bot_edit_messageB | Replace the text of a message the bot sent earlier. Changes a real message; confirm with the user first. |
| bot_delete_messageA | Delete a message the bot may delete (its own, or as admin). Irreversible; confirm with the user first. |
| bot_get_new_messagesA | Get messages people sent the bot since the last check, from all chats, oldest first, and mark them read. Each message has chat_id (reply with it), from, kind (text, photo, button, ...), text, and file_id for media (see bot_download_file). unread_left counts the rest. Fails while a webhook is set (see bot_get_webhook_info). |
| bot_list_chatsA | List the chats this bot has talked in, newest first, with unread count and last message. Use to find chat ids. |
| bot_read_chatA | Show a chat's recent messages in both directions, oldest first, and mark the chat read. Comes from the local store (everything this server received or sent); Bale itself keeps no history. |
| bot_search_messagesA | Search stored messages by text, newest first. Persian/Arabic yeh, kaf, digits and ZWNJ match each other. Long texts are cut with a '...(+N chars)' marker; bot_read_chat shows them whole. |
| bot_wait_for_replyA | Wait until someone writes in a chat or presses a button, then return the new messages (marked read). Use after bot_send_message. Returns timed_out=true and no messages if nobody answered; call again to keep waiting. |
| bot_download_fileA | Download a file someone sent the bot (max 20 MB) and return its local path. Never overwrites (-1, -2, ... suffix). |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 13 tools
Most tools map to a distinct resource+action, but message retrieval is split across three tools (bot_get_new_messages for unread across all chats, bot_read_chat for one chat's recent history, bot_search_messages for text search), which could cause some misselection. Descriptions do a good job distinguishing them (unread vs. history vs. search, and which mark read), keeping overlap manageable.
Every tool follows a consistent bot_verb_noun snake_case pattern (bot_get_me, bot_send_message, bot_delete_message, bot_list_chats, bot_download_file). Verb choices are predictable (get/send/edit/delete/list/read/search/wait/download).
13 tools is well within the ideal 3-15 range and each tool earns its place in a messaging-bot workflow. Nothing feels padded or missing at the count level.
Covers the core messaging lifecycle well: send/edit/delete, read/search, wait-for-reply, file send/download, chat listing, chat info, and identity/webhook checks. Minor gaps exist—no tool to set/clear a webhook (only get_webhook_info), and no forward/pin or explicit button-keyboard send—but these are edge cases agents can largely work around.