MAX AI secretary guide
clawbot-max-guide
A set of simplified Python examples for assembling a personal AI secretary in the MAX messenger via the Bot API, User API and MCP
High risk
We rate an entry high when the tool writes to external systems, handles money, production databases or secrets, or runs arbitrary commands. The CLI installs it only with your consent.
Why this level
- Uses MAX's unofficial User API via a secondary SIM, not the official Bot API
- Misuse (mass mailing, automating on behalf of other people) falls under 152-FZ, 38-FZ and Criminal Code art. 159, which the README warns about explicitly
Install
Manual install
pip install -r examples/requirements.txtDependencies for the examples: httpx, msgpack.
This is third-party code. Review the repository files before installing.
What it does
The project is not a finished server but a scaffold from an article on building a personal AI secretary for MAX: the agent reads messages via a secondary SIM (User API, not your main number), classifies intent, optionally calls an MCP server built from 7 tool stubs, and carries on a conversation on your behalf until confirmation, mirroring every reply into the owner's service chat. It ships seven examples: Bot API long polling, User API sending with the required cid field, a persistent TLS-socket listener, an intent classifier, an MCP server skeleton, mirroring the conversation to the owner via the Bot API, and an allowlist structure for auto-replies. The material comes with a separate LEGAL.md covering what is and is not allowed under 152-FZ, 38-FZ and Article 159 of the Criminal Code.
Who it is for. For developers ready to finish the examples into working code who want a personal, everyday AI secretary in MAX on their own number.
Good fit when
- You want a starting example for reading and sending messages via MAX's unofficial User API
- You need personal everyday automation: a bot that books a table or carries a conversation on your behalf with confirmation
- You want a rundown of the legal boundaries of such automation under 152-FZ and 38-FZ before writing anything
Not a fit when
- You want a ready working server: mcp_server_stub.py is a 7-stub skeleton, not a working MCP server, you finish it yourself
- You are planning commercial mailing, auto-dialing, or automation on behalf of other people: the README explicitly calls this illegal and out of scope
- You need a production system: the author explicitly warns this is not one
Example request
Book a table with this number for tomorrow at 7pm for twoLimitations
This is not production code: the examples are simplified and need further work for your own stack, including the MCP server itself, which in the repository is only a 7-tool stub. It uses MAX's unofficial User API via a secondary SIM, not an official protocol. The LLM call in the listener example is a call_your_llm() stub you must wire up yourself. The README explicitly frames the project as use-at-your-own-risk.
How to disable. Stop the user_api_listener.py script and delete the token file at ~/.config/clawbot-max/token.txt.
Security check
- Uses MAX's unofficial User API via a secondary SIM, not the official Bot API
- Misuse (mass mailing, automating on behalf of other people) falls under 152-FZ, 38-FZ and Criminal Code art. 159, which the README warns about explicitly
README in short
The README describes the architecture: two entry points (a MAX bot and a Telegram bot) feeding one LLM worker, an intent classifier and an MCP server, MAX User API access via a secondary SIM, and a persistent listener. It gives a six-step quick start, a table of seven example files mapped to sections of the source Habr article, a list of third-party unofficial MAX protocol implementations, and a bold legal warning pointing to LEGAL.md.
FAQ
Can I use my main number instead of a secondary SIM?
The author explicitly recommends only a secondary SIM, not the main number, and stresses the personal, everyday nature of the automation.
Is the example MCP server working?
No, examples/mcp_server_stub.py is a 7-tool skeleton that you need to finish for your own stack.
Related
An MCP server with n8n node and template knowledge: the agent picks nodes, validates configs and, with API access, creates workflows in your n8n
Zapier's official MCP plugin: the agent gets actions across thousands of apps through your Zapier account
Awesome Claude Skills by Composio
Awesome Claude Skills
A curated list of Claude skills and plugins, plus Composio's own automation skills for 78 SaaS apps
A plugin and CLI catalog for agents: generates command-line interfaces for GUI apps like GIMP and Blender and installs ready ones via CLI-Hub