max-mcp

# max-mcp Local MCP server for working with user session MAX from Claude Code and other MCP clients. ## Capabilities | Tool | Purpose | |---|---| | `list_chats` | List of dialogs, groups, and channels | | `get_chat` | Data of one chat or channel | | `read_messages` | Message history with pagination | | `search_messages` | Search for a substring in the history of a selected chat | | `list_channel_posts` | Channel publications, reactions, and statistics | | `dump_channel` | Batch download of a channel up to 1000 publications per call | | `send_message` | Sending a message or response | | `send_file` | Sending a file, photo, or video | > [!WARNING] > The project uses an unofficial client `maxapi-python` and a user session. The MAX protocol may change without warning, and automation may lead to account restrictions. For experiments, it's better to use a separate account and not make mass mailings. ## Requirements - macOS or Linux; - Python 3.11–3.13; - [`uv`](https://github.com/astral-sh/uv); - Claude Code or another client with MCP stdio support. ## Quick Start ### 1. Installation ```bash git clone https://github.com/renosaza/max-mcp.git ~/max-mcp cd ~/max-mcp uv sync --frozen ``` ### 2. Authorization By QR code: ```bash uv run max-mcp-login login-qr ``` In the MAX mobile application, open the binding of a new device and scan the QR code from the terminal. By phone number: ```bash uv run max-mcp-login login-sms --phone +79991234567 ``` The session is stored in `~/.max-mcp/`. The directory receives permissions `0700`, session files — `0600`. ### 3. Connection to Claude Code ```bash claude mcp add max-mcp --scope user \ -- uv run --directory "$HOME/max-mcp" max-mcp ``` Verification: ```bash claude mcp list ``` In an already open Claude Code session, execute `/mcp` and reconnect the server or start a new chat. ## Request Examples ```text Show the last 20 chats of MAX. ``` ```text Find messages with the word "contract" in chat 123456, reviewing no more than 1000 messages. ``` ```text Unload publications of the channel -69531237780213 in parts and save the result in JSON. ``` ```text Send a file /Users/me/Documents/report.pdf with the signature "Report" to chat 123456. ``` Before write operations, check `chat_id`, text, and file path. ## File Sending By default, only files from: - `~/Downloads`; - `~/Documents`; - `/tmp`. A custom list of directories is set via `MAX_MCP_SEND_ROOTS`: ```bash export MAX_MCP_SEND_ROOTS="$HOME/Desktop:/data/exports" ``` Paths within `~/.ssh`, `~/.aws`, `~/.max-mcp`, `/etc`, `/var`, and the macOS system keychain are prohibited even with an extended list. The final path must not be a symbolic link. ## Reauthorization ```bash rm -f ~/.max-mcp/session.db \ ~/.max-mcp/session.kind \ ~/.max-mcp/session.phone cd ~/max-mcp uv run max-mcp-login login-qr ``` ## Documentation - [Tools and response formats](docs/TOOLS.md) - [Diagnostics and recovery](docs/TROUBLESHOOTING.md) - [Development and testing](docs/DEVELOPMENT.md) ## Limitations - Message search is performed locally by sequential reading of history; - The `stats` and `reaction_info` scheme depends on the MAX response and is not fixed; - The message sender may return only a numeric identifier; - Full unloading of a large channel requires several calls to `dump_channel`; - After changing the internal MAX protocol, an update of `maxapi-python` or server code may be required. ## License MIT. See [LICENSE](LICENSE).