Bale Bot
PYPI · BALE-MCP
Private, local Bale bot for agents: read, search and answer messages, ask and wait, files.
Available components
Last scanned (14 hours ago)
Scores higher than 84% of PyPI servers
Category Communication
How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. How we score → Why this is hard to score →
Supply Chain Security100
- No malware found by supply-chain analysis.Pass
- No known CVEs affecting this package version or its production dependencies.Pass
- Runs hatchling.build at install time, a recognised build step with no custom scripting around it. View diagnostics → Pass
- 1 of 31 dependencies flagged as unhealthy. View diagnostics → Partial
Provenance & Transparency97
- Source repository is publicly reachable at the declared URL. View diagnostics → Pass
- Cryptographically verified build provenance (signed, bound to sepehr071/bale-mcp). View diagnostics → Pass
- Clear OSI-approved license (MIT).Pass
- Actively maintained (last published 0 days ago).Pass
- Disclosure check failed: no security disclosure policy was found in the source repository. See how to fix → Fail
Schema Quality & AI Usability75
- AI-judged instruction clarity (good).Pass
- Context-footprint check failed: tool/resource definitions use about 1439 tokens (~110/item across 13 items; 13 tools + 0 resources), over budget; trim descriptions and params. See how to fix → Fail
- Usage-examples check failed: none of the tools include examples. See how to fix → Fail
Stability & Change Management13
- Stability check failed: the tool surface changed between 0.1.0 and 0.2.1: 0 tool removals, 13 breaking changes, 0 additions. See how to fix → Fail
Tool Coverage100
- 100% of tools have a non-trivial description (not blank, and not just the tool's name).Pass
- 100% of tool parameters carry a description.Pass
Tool Safety100
- No prompt-injection markers were found in the server instructions, tool names or descriptions we captured.Pass
- All 3 tool(s) whose name or description implies an irreversible operation declare an MCP destructiveHint annotation.Pass
- An AI judge read all 14 captured unit(s) of tool text and found none that tries to manipulate the model reading it.Pass
Capabilities100
- Implements a current MCP spec version (2026-07-28).Pass
Every change we have recorded for this component, newest first. Security-relevant changes are always shown. ▲ marks a change for the better, ▼ a change for the worse; unmarked changes are neutral.
- 22 Oct 26 +1
- Stability: fail → unverified ▼ security
- Tool safety: pass → unverified ▼ security
- Capabilities: pass → unverified ▼ functional
- Tool coverage: 100 → unverified ▼ functional
- Schema quality: pass → fail ▼ functional
- Package version: 0.2.0 → 0.2.1 functional
- 21 Oct 26 0
- Package version: 0.1.2 → 0.2.0 functional
- 19 Oct 26 +1
- Security disclosure: unverified → fail ▼ functional
- 18 Oct 26 0
- Security disclosure: fail → unverified ▼ functional
- 16 Oct 26 −7
- Stability: 0.40 → unverified ▼ security
- Tool safety: pass → unverified ▼ security
- Stability: 0.40 → fail ▼ security
- Capabilities: pass → unverified ▼ functional
- Tool coverage: 100 → unverified ▼ functional
- Security disclosure: fail → unverified ▼ functional
- Schema quality: fail → pass ▲ functional
- Schema quality: excellent → good functional
- Package version: 0.1.2 → 0.2.0 functional
- 15 Oct 26 +39
- Injection markers: unverified → pass ▲ security
- Tool coverage: unverified → 100 ▲ functional
- Stability: unverified → 0.40 ▲ functional
- MCP protocol: unverified → pass ▲ functional
- 13 Oct 26 0
- Package version: 0.1.1 → 0.1.2 functional
- 12 Oct 26 −33
- Tool safety: pass → unverified ▼ security
- Stability: Stability not yet verified: we do not have a sandbox capture of the MCP schema this version of the package serves yet. security
- Capabilities: pass → unverified ▼ functional
- Tool coverage: 100 → unverified ▼ functional
- First check of Schema quality: unverified functional
- Package version: 0.1.0 → 0.1.1 functional
Diagnostic detail from the automated scan of this channel: what the scanner observed at each step, so you can see exactly where a check passed or failed. It is informational only and never changes the trust score.
Captured 22 Oct 2026 · Analysed pypi/bale-mcp@0.2.1
Provenance Verified
A signed build attestation was found and verified, binding this exact artifact to the source repository it claims to come from.
| Result | Verified |
|---|---|
| Ecosystem | pypi |
| Reason | Verified |
| Discovered via | Registry attestation endpoint |
| Source repo | sepehr071/bale-mcp |
| Certificate issuer | https://token.actions.githubusercontent.com |
| Certificate SAN | https://github.com/sepehr071/bale-mcp/.github/workflows/publish.yml@refs/tags/v0.2.1 |
| Rekor log index | 3390343325 |
| Predicate type | PyPI publish attestation https://docs.pypi.org/attestations/publish/v1 |
| Subject digest | sha256:584f5db6d4913e6d656fb174baebccec2e9dfd03377650eac6580a7a4e89e853 |
Background: How many MCP packages publish verified provenance →
Install scripts 1 script
| Hook | Tier | Command |
|---|---|---|
| build_backend | allowlisted | hatchling.build |
Background: Why install scripts are a supply-chain risk →
Dependencies 31 packages
| Packages resolved | 31 |
|---|---|
| No linked repository | 1 |
| Tree resolution | Complete |
Background: SBOMs and build attestations, explained →
The tools this component advertises to a client, with an estimated token cost for each. Expand a tool to see its parameters and schema. The per-tool counts are indicative and are not scored directly; the schema's total context footprint is one signal in Schema Quality & AI Usability. A tool's description is untrusted text the model reads on every call, which is what makes this list a security surface and not just an inventory: how tool poisoning works →
bot_delete_message Bot: delete message ~77
Delete a message the bot may delete (its own, or as admin). Irreversible; confirm with the user first.
| Name | Type | Req | Description |
|---|---|---|---|
| chat_id | – | yes | Chat id (number, e.g. 123456789) or public '@channel' username. See bot_list_chats. |
| message_id | integer | yes | Message id to delete. |
No output schema declared.
No examples provided.
bot_download_file Bot: download file ~71
Download a file someone sent the bot (max 20 MB) and return its local path. Never overwrites (-1, -2, ... suffix).
| Name | Type | Req | Description |
|---|---|---|---|
| file_id | string | yes | file_id from a received message. |
| folder | – | – | Folder to save into. Default ~/.bale-mcp/files. |
No output schema declared.
No examples provided.
bot_edit_message Bot: edit message ~87
Replace the text of a message the bot sent earlier. Changes a real message; confirm with the user first.
| Name | Type | Req | Description |
|---|---|---|---|
| chat_id | – | yes | Chat id (number, e.g. 123456789) or public '@channel' username. See bot_list_chats. |
| message_id | integer | yes | Id of a text message the bot sent. |
| text | string | yes | New text. |
No output schema declared.
No examples provided.
bot_get_chat Bot: chat info ~54
Get a chat's type, title or name, username and description.
| Name | Type | Req | Description |
|---|---|---|---|
| chat_id | – | yes | Chat id (number, e.g. 123456789) or public '@channel' username. See bot_list_chats. |
No output schema declared.
No examples provided.
bot_get_me Bot: who am I ~26
Check BALE_BOT_TOKEN and show the bot's id, username and name.
Input schema present but exposes no named parameters.
No output schema declared.
No examples provided.
bot_get_new_messages Bot: new messages ~100
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).
| Name | Type | Req | Description |
|---|---|---|---|
| limit | integer | – | Max messages. |
No output schema declared.
No examples provided.
bot_get_webhook_info Bot: webhook status ~33
Show whether a webhook is set (url empty = the reading tools work), pending updates and the last error.
Input schema present but exposes no named parameters.
No output schema declared.
No examples provided.
bot_list_chats Bot: list chats ~44
List the chats this bot has talked in, newest first, with unread count and last message. Use to find chat ids.
| Name | Type | Req | Description |
|---|---|---|---|
| limit | integer | – | Max chats. |
No output schema declared.
No examples provided.
bot_read_chat Bot: read chat ~74
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.
| Name | Type | Req | Description |
|---|---|---|---|
| chat_id | integer | yes | Numeric chat id (see bot_list_chats). |
| limit | integer | – | Max messages. |
No output schema declared.
No examples provided.
bot_search_messages Bot: search messages ~98
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.
| Name | Type | Req | Description |
|---|---|---|---|
| chat_id | – | – | Only this chat. |
| limit | integer | – | Max messages. |
| max_chars | integer | – | Cut each text to this length. |
| query | string | yes | Text to find. |
No output schema declared.
No examples provided.
bot_send_file Bot: send file ~138
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 and the working directory).
| Name | Type | Req | Description |
|---|---|---|---|
| caption | – | – | Optional caption. |
| chat_id | – | yes | Chat id (number, e.g. 123456789) or public '@channel' username. See bot_list_chats. |
| kind | string | yes | How Bale shows the file. |
| source | string | yes | http(s) URL, or local file path (max 50 MB; see BALE_MCP_SEND_DIRS). |
No output schema declared.
No examples provided.
bot_send_message Bot: send message ~181
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.
| Name | Type | Req | Description |
|---|---|---|---|
| buttons | – | – | Inline buttons as rows of labels, e.g. [['Yes', 'No']]. A press arrives as kind 'button' (text = label, cut to 64 bytes). |
| chat_id | – | yes | Chat id (number, e.g. 123456789) or public '@channel' username. See bot_list_chats. |
| reply_to_message_id | – | – | Reply to this message id in the same chat. |
| text | string | yes | Message text. |
No output schema declared.
No examples provided.
bot_wait_for_reply Bot: wait for reply ~120
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.
| Name | Type | Req | Description |
|---|---|---|---|
| after_message_id | – | – | Only messages newer than this id: pass the message_id you sent; a button press on it counts. |
| chat_id | integer | yes | Numeric chat id (see bot_list_chats). |
| timeout_seconds | integer | – | How long to wait; use less if your client cancels long calls. |
No output schema declared.
No examples provided.
How do I install the Bale Bot MCP server?
Bale Bot runs locally as a PyPI package, launched with uvx bale-mcp. Ready-made configuration for Claude, Cursor, VS Code, Codex and 5 more is on this page, copied from each client's own documentation.
pypi · bale-mcp
claude mcp add sepehr071-bale-mcp -- uvx bale-mcp
What is the Bale Bot MCP server?
Bale Bot is an MCP server listed in the public MCP registry as io.github.sepehr071/bale-mcp. Private, local Bale bot for agents: read, search and answer messages, ask and wait, files. This page covers its PyPI package (bale-mcp).
Is the Bale Bot MCP server safe to use?
Bale Bot scores 83 out of 100 on VerifyMCP. We found no known CVEs affecting it as of 22 October 2026. Its build provenance is signed and verified. That is a record of what we were able to check automatically, not an endorsement. The category breakdown on this page shows every signal behind the number, including the ones we could not confirm.
What tools does the Bale Bot MCP server expose?
Bale Bot exposes 13 tools: bot_get_me, bot_get_chat, bot_get_webhook_info, bot_send_message, bot_send_file, and 8 more. Their descriptions and schemas cost roughly 1,103 tokens of context every time the server is loaded.
Is the Bale Bot MCP server still maintained?
Bale Bot is still listed as active in the MCP registry. We last reached this channel on 22 October 2026. Those dates come from our own scans of the registry and the channel itself, not from anything the publisher announced.
What licence is the Bale Bot MCP server under?
Bale Bot declares the MIT licence, which is OSI-approved. That covers the source only, and says nothing about the cost of any service it calls.