# Bale Bot (pypi · bale-mcp)

Private, local Bale bot for agents: read, search and answer messages, ask and wait, files.

- Trust score: 83/100 (high trust)
- Change this week: −5
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-10-22

## Components

- pypi · `bale-mcp`: 83/100 (this document), [markdown](https://verifymcp.io/servers/sepehr071-bale-mcp/bale-mcp.md), [page](https://verifymcp.io/servers/sepehr071-bale-mcp/bale-mcp)

## Channel facts

- Registry: `pypi`
- Package: `bale-mcp`
- Version: `0.2.1`
- Transport: `stdio`

## Trust breakdown

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. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-10-22.

- **Supply Chain Security**: 100/100
  - No malware found by supply-chain analysis.
  - No known CVEs affecting this package version or its production dependencies.
  - Runs hatchling.build at install time, a recognised build step with no custom scripting around it.
  - 1 of 31 dependencies flagged as unhealthy.
- **Provenance & Transparency**: 97/100
  - Source repository is publicly reachable at the declared URL.
  - Cryptographically verified build provenance (signed, bound to sepehr071/bale-mcp).
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 0 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 75/100
  - AI-judged instruction clarity (good).
  - 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.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 13/100
  - Stability check failed: the tool surface changed between 0.1.0 and 0.2.1: 0 tool removals, 13 breaking changes, 0 additions.
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
- **Tool Safety**: 100/100
  - No prompt-injection markers were found in the server instructions, tool names or descriptions we captured.
  - All 3 tool(s) whose name or description implies an irreversible operation declare an MCP destructiveHint annotation.
  - An AI judge read all 14 captured unit(s) of tool text and found none that tries to manipulate the model reading it.
- **Capabilities**: 100/100
  - Implements a current MCP spec version (2026-07-28).

## Install

### 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.

### Claude

```bash
claude mcp add sepehr071-bale-mcp -- uvx bale-mcp
```

### Cursor

```json
{
  "mcpServers": {
    "sepehr071-bale-mcp": {
      "command": "uvx",
      "args": [
        "bale-mcp"
      ]
    }
  }
}
```

### VS Code

```json
{
  "servers": {
    "sepehr071-bale-mcp": {
      "command": "uvx",
      "args": [
        "bale-mcp"
      ]
    }
  }
}
```

### Codex

```bash
codex mcp add sepehr071-bale-mcp -- uvx bale-mcp
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sepehr071-bale-mcp": {
      "type": "local",
      "command": [
        "uvx",
        "bale-mcp"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add sepehr071-bale-mcp --command uvx --arg bale-mcp
```

### Hermes

```yaml
mcp_servers:
  sepehr071-bale-mcp:
    command: "uvx"
    args: ["bale-mcp"]
```

### Netclaw

```json
{
  "McpServers": {
    "sepehr071-bale-mcp": {
      "Transport": "stdio",
      "Command": "uvx",
      "Arguments": [
        "bale-mcp"
      ]
    }
  }
}
```

### Vellum

```bash
assistant mcp add sepehr071-bale-mcp -t stdio -c uvx -a bale-mcp
```

### Other

```json
{
  "mcpServers": {
    "sepehr071-bale-mcp": {
      "command": "uvx",
      "args": [
        "bale-mcp"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-10-22 (score 83, +1)

- [security regression] Stability: fail → unverified
- [security regression] Tool safety: pass → unverified
- [functional regression] Capabilities: pass → unverified
- [functional regression] Tool coverage: 100 → unverified
- [functional regression] Schema quality: pass → fail
- [functional] Package version: 0.2.0 → 0.2.1

### 2026-10-21 (score 82, 0)

- [functional] Package version: 0.1.2 → 0.2.0

### 2026-10-19 (score 82, +1)

- [functional regression] Security disclosure: unverified → fail

### 2026-10-18 (score 81, 0)

- [functional regression] Security disclosure: fail → unverified

### 2026-10-16 (score 81, −7)

- [security regression] Stability: 0.40 → unverified
- [security regression] Tool safety: pass → unverified
- [security regression] Stability: 0.40 → fail
- [functional regression] Capabilities: pass → unverified
- [functional regression] Tool coverage: 100 → unverified
- [functional regression] Security disclosure: fail → unverified
- [functional improvement] Schema quality: fail → pass
- [functional] Schema quality: excellent → good
- [functional] Package version: 0.1.2 → 0.2.0

### 2026-10-15 (score 88, +39)

- [security improvement] Injection markers: unverified → pass
- [functional improvement] Tool coverage: unverified → 100
- [functional improvement] Stability: unverified → 0.40
- [functional improvement] MCP protocol: unverified → pass

### 2026-10-13 (score 49, 0)

- [functional] Package version: 0.1.1 → 0.1.2

### 2026-10-12 (score 49, −33)

- [security regression] 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.
- [functional regression] Capabilities: pass → unverified
- [functional regression] Tool coverage: 100 → unverified
- [functional] First check of Schema quality: unverified
- [functional] Package version: 0.1.0 → 0.1.1

## MCP tools (13)

### `bot_get_me` (~26 tokens)

Bot: who am I

Check BALE_BOT_TOKEN and show the bot's id, username and name.

### `bot_get_chat` (~54 tokens)

Bot: chat info

Get a chat's type, title or name, username and description.

Input parameters:

- `chat_id` (required): Chat id (number, e.g. 123456789) or public '@channel' username. See bot_list_chats.

### `bot_get_webhook_info` (~33 tokens)

Bot: webhook status

Show whether a webhook is set (url empty = the reading tools work), pending updates and the last error.

### `bot_send_message` (~181 tokens)

Bot: send message

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.

Input parameters:

- `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` (required): 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, required): Message text.

### `bot_send_file` (~138 tokens)

Bot: send file

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).

Input parameters:

- `caption`: Optional caption.
- `chat_id` (required): Chat id (number, e.g. 123456789) or public '@channel' username. See bot_list_chats.
- `kind` (string, required): How Bale shows the file.
- `source` (string, required): http(s) URL, or local file path (max 50 MB; see BALE_MCP_SEND_DIRS).

### `bot_edit_message` (~87 tokens)

Bot: edit message

Replace the text of a message the bot sent earlier. Changes a real message; confirm with the user first.

Input parameters:

- `chat_id` (required): Chat id (number, e.g. 123456789) or public '@channel' username. See bot_list_chats.
- `message_id` (integer, required): Id of a text message the bot sent.
- `text` (string, required): New text.

### `bot_delete_message` (~77 tokens)

Bot: delete message

Delete a message the bot may delete (its own, or as admin). Irreversible; confirm with the user first.

Input parameters:

- `chat_id` (required): Chat id (number, e.g. 123456789) or public '@channel' username. See bot_list_chats.
- `message_id` (integer, required): Message id to delete.

### `bot_get_new_messages` (~100 tokens)

Bot: new messages

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).

Input parameters:

- `limit` (integer): Max messages.

### `bot_list_chats` (~44 tokens)

Bot: list chats

List the chats this bot has talked in, newest first, with unread count and last message. Use to find chat ids.

Input parameters:

- `limit` (integer): Max chats.

### `bot_read_chat` (~74 tokens)

Bot: read chat

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.

Input parameters:

- `chat_id` (integer, required): Numeric chat id (see bot_list_chats).
- `limit` (integer): Max messages.

### `bot_search_messages` (~98 tokens)

Bot: search messages

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.

Input parameters:

- `chat_id`: Only this chat.
- `limit` (integer): Max messages.
- `max_chars` (integer): Cut each text to this length.
- `query` (string, required): Text to find.

### `bot_wait_for_reply` (~120 tokens)

Bot: wait for reply

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.

Input parameters:

- `after_message_id`: Only messages newer than this id: pass the message_id you sent; a button press on it counts.
- `chat_id` (integer, required): Numeric chat id (see bot_list_chats).
- `timeout_seconds` (integer): How long to wait; use less if your client cancels long calls.

### `bot_download_file` (~71 tokens)

Bot: download file

Download a file someone sent the bot (max 20 MB) and return its local path. Never overwrites (-1, -2, ... suffix).

Input parameters:

- `file_id` (string, required): file_id from a received message.
- `folder`: Folder to save into. Default ~/.bale-mcp/files.

## Diagnostics

Captured diagnostic sections: Provenance, Install scripts, Dependencies. The full working is on the page: https://verifymcp.io/servers/sepehr071-bale-mcp/bale-mcp#diagnostics

## Score history

- 2026-10-22: 83
- 2026-10-21: 82
- 2026-10-20: 82
- 2026-10-19: 82
- 2026-10-18: 81
- 2026-10-17: 81
- 2026-10-16: 81
- 2026-10-15: 88
- 2026-10-14: 49
- 2026-10-13: 49
- 2026-10-12: 49
- 2026-10-07: 82
- 2026-10-04: 82
- 2026-10-03: 67

## Common questions

### 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.

## Links

- PyPI project: https://pypi.org/project/bale-mcp/
- Socket report: https://socket.dev/pypi/package/bale-mcp
- Repository: https://github.com/sepehr071/bale-mcp
- Changelog RSS feed: https://verifymcp.io/servers/sepehr071-bale-mcp/bale-mcp.xml
- Changelog JSON feed: https://verifymcp.io/servers/sepehr071-bale-mcp/bale-mcp.json
- HTML version of this page: https://verifymcp.io/servers/sepehr071-bale-mcp/bale-mcp