max-mcp

# max-mcp 本地MCP服务器，用于与Claude Code和其他MCP客户端配合使用MAX用户会话。 ## 功能 | 工具 | 用途 | |---|---| | `list_chats` | 聊天列表、群组和频道 | | `get_chat` | 单个聊天室或频道的资料 | | `read_messages` | 消息历史记录，支持分页 | | `search_messages` | 在选定的聊天室中搜索子字符串 | | `list_channel_posts` | 频道的发布内容、反应和统计数据 | | `dump_channel` | 批量下载频道内容，最多1000条发布内容 | | `send_message` | 发送消息或回复 | | `send_file` | 发送文件、照片或视频 | > [!WARNING] > 该项目使用非官方客户端`maxapi-python`和用户会话。MAX协议可能会在未通知的情况下更改，自动化操作可能会导致账户限制。建议使用单独的账户进行实验，避免进行大规模的群发消息。 ## 要求 - macOS 或 Linux; - Python 3.11–3.13; - [`uv`](https://github.com/astral-sh/uv); - Claude Code 或其他支持MCP stdio的客户端。 ## 快速开始 ### 1. 安装 ```bash git clone https://github.com/renosaza/max-mcp.git ~/max-mcp cd ~/max-mcp uv sync --frozen ``` ### 2. 授权 通过二维码： ```bash uv run max-mcp-login login-qr ``` 在MAX移动应用程序中，打开新的设备绑定并扫描终端中的二维码。 通过手机号： ```bash uv run max-mcp-login login-sms --phone +79991234567 ``` 会话存储在 `~/.max-mcp/` 目录中。该目录的权限为 `0700`，会话文件的权限为 `0600`。 ### 3. 连接到Claude Code ```bash claude mcp add max-mcp --scope user \ -- uv run --directory "$HOME/max-mcp" max-mcp ``` 检查： ```bash claude mcp list ``` 在已经打开的Claude Code会话中，执行 `/mcp` 并重新连接服务器或开始新的聊天。 ## 请求示例 ```text 显示最近的20个MAX聊天记录。 ``` ```text 在聊天室123456中查找包含字符串“合同”的消息，查看不超过1000条记录。 ``` ```text 分批下载频道-69531237780213的发布内容并保存为JSON格式。 ``` ```text 向聊天室123456发送文件 /Users/me/Documents/report.pdf，并附上签名“报告”。 ``` 在执行写入操作之前，请检查 `chat_id`、文本和文件路径。 ## 发送文件 默认情况下，仅允许从以下目录发送文件： - `~/Downloads`; - `~/Documents`; - `/tmp`. 可以通过设置 `MAX_MCP_SEND_ROOTS` 环境变量自定义目录列表： ```bash export MAX_MCP_SEND_ROOTS="$HOME/Desktop:/data/exports" ``` 在 `~/.ssh`、`~/.aws`、`~/.max-mcp`、` /etc`、`/var` 和 macOS系统密钥存储区内的路径即使在扩展列表中也不被允许。最终路径不能是符号链接。 ## 重新授权 ```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 ``` ## 文档 - [工具和响应格式](docs/TOOLS.md) - [诊断和故障排除](docs/TROUBLESHOOTING.md) - [开发和测试](docs/DEVELOPMENT.md) ## 限制 - 消息搜索通过本地顺序读取历史记录实现； - `stats` 和 `reaction_info` 架构取决于MAX的响应且未固定； - 消息发送者可能仅以数字ID返回； - 大型频道的完整下载需要多次调用 `dump_channel`； - 在更改MAX内部协议后，可能需要更新 `maxapi-python` 或服务器代码。 ## License MIT. See [LICENSE](LICENSE).