bale-account-mcp
# bale-account-mcp
MCP server that lets an AI agent (Claude Code, Claude Desktop, Cursor, …) manage **your personal Bale (بله) account**: read and search chats, send messages and files, download files, manage groups and contacts.
- **Zero dependencies.** The MCP protocol, protobuf codec and gRPC-Web client are written from scratch on Node's standard library. No third-party code is installed or run. The source is strict TypeScript that Node runs directly; `typescript` and `@types/node` are dev dependencies used only for type checking.
- **Free.** It uses the same API web.bale.ai uses with your own account; there is no paid API involved.
- For a bot instead of your own account, see the sibling project `bale-bot-mcp` (official Bot API).
> **Unofficial.** Bale has no public API for personal accounts. This speaks the web client's protocol, so it can break when Bale changes it, and automating a personal account may be against Bale's terms. Use it for your own account, at your own risk.
## Tools (24)
| Read | |
|---|---|
| `bale_me` | Which account is logged in |
| `bale_list_chats` | Chats (private, groups, channels) with unread counts and last message |
| `bale_get_unread` | Unread messages across chats (does not mark them read) |
| `bale_read_chat` | A chat's messages, with paging |
| `bale_search_messages` | Persian-aware search over recent history (Bale has no server-side search for accounts) |
| `bale_wait_for_message` | Wait for the next incoming message |
| `bale_download_file` | Download a file from a message |
| `bale_get_user` | Profile: name, username, bio, contact/bot flags |
| `bale_find_contact` | Find a user by phone number |
| `bale_list_contacts` | Your contacts |
| `bale_get_group` | Group/channel details |
| `bale_list_group_members` | Members with admin flags |
| `bale_get_group_invite_link` | Invite link |
| Write (hidden with `BALE_READ_ONLY=1`) | |
|---|---|
| `bale_send_message` | Send text (replies supported; long text is split) |
| `bale_send_file` | Send a document, photo, video, audio, voice or GIF |
| `bale_edit_message` | Edit your message |
| `bale_delete_message` | Delete for everyone or just you |
| `bale_forward_message` | Forward a message |
| `bale_mark_read` | Mark a chat read |
| `bale_join_group` / `bale_leave_group` | Join by `ble.ir/join/…` link / leave |
| `bale_create_group` | Create a group or channel (see Status) |
| `bale_add_group_members` / `bale_remove_group_member` | Manage members |
## Setup
Requires Node.js 22.18+ (it runs the `.ts` files directly). Nothing to install.
1. Log in (you type your phone number and the code yourself; only the resulting session is stored):
```bash
npm run login
```
The session goes to `~/.bale-account-mcp/session.json` (mode 600). It shows up in Bale → Settings → Devices as **bale-account-mcp**; end it there to revoke access. `npm run login -- --logout` deletes the local file.
2. Add to Claude Code, from the install clone described below (read-only first is a good idea):
```bash
claude mcp add bale-account --scope user -e BALE_READ_ONLY=1 -- node ~/.local/share/bale-account-mcp/src/index.ts
```
Drop `-e BALE_READ_ONLY=1` to allow sending, editing and group changes.
## Install / update
Run the server from its own clone of `main`, not from the folder you develop in. Branch work there can then never break the server your MCP client is running.
```bash
git clone --branch main https://github.com/AliMilani/bale-account-mcp.git ~/.local/share/bale-account-mcp
```
Update it with:
```bash
git -C ~/.local/share/bale-account-mcp pull
```
Then restart (or reconnect) the MCP client. The runtime has no dependencies, so nothing needs installing after a pull. The session in `~/.bale-account-mcp/` is shared by every clone, so you don't log in again.
**Upgrading from the JavaScript version.** Older versions were registered with `src/index.js`. Since the TypeScript port the entry file is `src/index.ts`, so after the pull the old registration points at a file that no longer exists. Register it again with the new path (Node 22.18+ is required):
```bash
claude mcp remove bale-account -s user
```
```bash
claude mcp add bale-account --scope user -e BALE_READ_ONLY=1 -- node ~/.local/share/bale-account-mcp/src/index.ts
```
## Configuration
| Variable | Default | Meaning |
|---|---|---|
| `BALE_ACCOUNT_DIR` | `~/.bale-account-mcp` | Session, chat-name cache, downloads |
| `BALE_READ_ONLY` | off | `1` exposes only the read tools |
| `BALE_ALLOWED_CHATS` | all | Comma list of chat ids; others are hidden and never touched |
| `BALE_SEND_DIRS` | `<dir>/files` | Folders `bale_send_file` may read from (symlinks resolved first) |
| `BALE_DEBUG` | off | Dump raw responses to stderr (never auth responses). Contains private messages: debugging only |
## Security
- **The session file is your account.** Anyone with `session.json` can read and send as you. It is created with mode 600 in a 700 folder, never printed, and scrubbed from error messages.
- The session cookie is only sent to Bale's own hosts (`*.bale.ai`, `*.ble.ir`), including for file uploads.
- Messages, names and files come from other people. Tool descriptions and server instructions tell the agent to treat them as data, not instructions; still, give an agent write access only when you mean to. `BALE_READ_ONLY` and `BALE_ALLOWED_CHATS` limit the blast radius.
- Uploads only from `BALE_SEND_DIRS`, and never credential files (`.ssh`, `.aws`, `session.json`, `*.token`, keys, `.env`…) even if that folder is set too broadly. Downloads stream to disk with a size cap and never overwrite.
- `BALE_ALLOWED_CHATS` applies to every tool: chats, groups, users and contacts; joining and creating groups is disabled while it is set.
- The device registers with a random per-install id and the honest title `bale-account-mcp`.
## How it works
Bale's web app talks gRPC-Web to `https://next-ws.bale.ai/<service>/<Method>` with the session JWT as the `access_token` cookie. Every tool is one or a few of these stateless calls. Message ids are random 64-bit numbers chosen by the client; deleting or forwarding needs the message's `date_ms`, which `bale_read_chat` returns.
The protocol was learned by **reading** (never running) the aiobale library and Bale's own public web-app JavaScript, then checked against live responses.
> Warning found during that research: in October 2026 the GitHub repos `aminmadaniofficial/aiobale` and `aminmadaniofficial/bale-mcp-server` received an injected GitHub Actions workflow (`security-audit.yml`) that harvests secrets from the repo and its history and posts them to a remote IP. Do not fork them with Actions enabled.
## Status
Verified live on a real account: list chats, unread, read chat, search, contacts, user profile, group info, members, find by phone, wait for message; send text, photo and document; edit; forward; mark read; delete; download (byte-identical).
Not yet verified live: join, leave, add/remove members, invite link. `bale_create_group` currently gets `WRONG_GROUP_TITLE` from Bale even though the request matches the web app's own definition; possibly a restriction on newly logged-in devices.
## Development
- [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md): code layout, adding a tool, live testing, security invariants, known issues and roadmap
- [docs/PROTOCOL.md](docs/PROTOCOL.md): Bale's web API, quirks, and how to find field numbers
- [CLAUDE.md](CLAUDE.md): short rules for AI agents working on this repo
```bash
npm ci --ignore-scripts # dev dependencies (typescript, @types/node), for typecheck only
npm run typecheck # tsc --noEmit, strict
npm test # mock gRPC-Web suite, no network
npm run call -- --list # call tools from the shell against the real account
npm run proto -- LoadDialogs # real field numbers from web.bale.ai's bundle
```
## License
[MIT](LICENSE)
TDQS
Scored across 24 tools
Each tool maps to a distinct resource/action pair: chat listing, message reading, searching, waiting, sending, editing, deleting, forwarding, file transfer, contact lookup, and group administration are separable. Overlaps such as get_unread vs list_chats and read_chat vs search_messages are clarified by descriptions and different return scopes.
The set is overwhelmingly consistent: all names use the bale_ prefix and snake_case verb_noun style, e.g. bale_send_message, bale_list_chats, bale_remove_group_member. The main exception is bale_me, which is a status/identity convenience rather than a verb_noun operation.
At 24 tools this is on the heavy side, but the count reflects a genuinely broad messaging surface covering messages, files, contacts, profiles, and group administration. Most tools earn their place, though the set is larger than the typical 3-15 sweet spot.
Core messaging lifecycle is well covered: read/search/unread/wait, send/edit/delete/forward, file send/download, contact lookup, and group create/join/leave/member management. Minor gaps remain around richer group administration (promote/admin, update group info) and message actions such as replies or reactions.