Bale Bot MCP Server
by sepehr071io.github.sepehr071/bale-mcpv0.1.0
Private, local Bale bot for agents: read, search and answer messages, ask and wait, files.
context tax
queued
security
queued
cold start
queued
freshness
Active3d ago
Install Bale Bot MCP server
Install in Claude Code
claude mcp add bale -e BALE_BOT_TOKEN='<bale-bot-token>' -- uvx bale-mcpInstall in Cursor
{
"mcpServers": {
"bale": {
"command": "uvx",
"args": [
"bale-mcp"
],
"env": {
"BALE_BOT_TOKEN": "<bale-bot-token>"
}
}
}
}Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (project).
Install in Claude Desktop
{
"mcpServers": {
"bale": {
"command": "uvx",
"args": [
"bale-mcp"
],
"env": {
"BALE_BOT_TOKEN": "<bale-bot-token>"
}
}
}
}Settings → Developer → Edit Config (claude_desktop_config.json), then restart.
Install in VS Code
{
"servers": {
"bale": {
"type": "stdio",
"command": "uvx",
"args": [
"bale-mcp"
],
"env": {
"BALE_BOT_TOKEN": "<bale-bot-token>"
}
}
}
}Add to .vscode/mcp.json in your workspace.
Install in Windsurf
{
"mcpServers": {
"bale": {
"command": "uvx",
"args": [
"bale-mcp"
],
"env": {
"BALE_BOT_TOKEN": "<bale-bot-token>"
}
}
}
}Add to ~/.codeium/windsurf/mcp_config.json.
Configuration
| Variable | Required | Secret | Description |
|---|---|---|---|
| BALE_BOT_TOKEN | yes | yes | Bot token from @botfather in Bale (https://ble.ir/botfather). |
| BALE_ALLOWED_CHATS | — | — | Comma-separated chat ids or @usernames the bot may read and message; all other chats are ignored. Recommended. |
| BALE_MCP_DB | — | — | Local message history file (default ~/.bale-mcp/messages.db); ':memory:' keeps nothing on disk. |
| BALE_MCP_PROXY | — | — | Optional HTTP proxy URL for every request; system proxy settings are ignored. |
Freshness
Active — last maintenance signal 3d ago. The newest of the signals below sets the band.
Last commit (default branch)
2026-10-06 · 3d ago · GitHub
Latest release
2026-10-03 · 6d ago · GitHub · v0.1.0
Package published
no data · npm/PyPI
Registry entry updated
2026-10-03 · 6d ago · official registry · v0.1.0
FAQ
›How do I install the Bale Bot MCP server in Claude Code?
Run: claude mcp add bale -e BALE_BOT_TOKEN='<bale-bot-token>' -- uvx bale-mcp. For Cursor, VS Code, Claude Desktop and Windsurf, use the install tabs above.
›Does Bale Bot require an API key?
Yes. It expects BALE_BOT_TOKEN, of which 1 is a secret.
›Can I use Bale Bot as a remote (hosted) MCP server?
No hosted endpoint is published; it runs locally over stdio.
›Is Bale Bot in the official MCP registry?
Yes, as io.github.sepehr071/bale-mcp.