max-messenger

mcp-max-messenger

MAX Messenger 用の初の MCP サーバー — VK が提供するロシアの国民的メッセンジャーです（ユーザー数 7,500 万人以上）。

AI クライアント（Claude Desktop、Cursor、n8n など、MCP 互換アプリ）を MAX に接続して、メッセージの送受信、チャットやメンバーの管理、メディアの送信、ボタン操作への対応、HTML／Markdown による書式設定を、オープンな Model Context Protocol 標準を通じて利用できます。

MAX Bot API を全面的にカバーする21 個のツールを備えています。

---

MAX を選ぶ理由

• 🇷🇺 ロシア国内のすべてのスマートフォンへのプリインストールが義務付けられている国民的メッセンジャーです（2025 年 9 月）
• 📱 登録ユーザー数 7,500 万人以上
• 🏢 政府機関や大企業への導入がデジタル開発省に推奨されています
• 🤖 公式 SDK（TypeScript、Python、Go、Java、PHP）を備えたフル機能の Bot API

---

クイックスタート

前提条件

• Node.js 18+
• MAX ボットトークン（max.ru でボットを作成してください）

Claude Desktop／Cursor（stdio モード）

Claude Desktop の設定に追加してください。

Mac： ~/Library/Application Support/Claude/claude_desktop_config.json Windows： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "max-messenger": {
      "command": "npx",
      "args": ["-y", "@woyax/mcp-max-messenger"],
      "env": {
        "MAX_TOKEN": "YOUR_BOT_TOKEN"
      }
    }
  }
}

Claude Desktop を再起動すると、MAX のツールが自動的に表示されます。

リモート／ホストモード（HTTP）

MAX_TOKEN=YOUR_BOT_TOKEN MCP_TRANSPORT=http MCP_PORT=3000 npx @woyax/mcp-max-messenger

任意の MCP クライアントを http://your-server:3000/mcp に接続してください。

---

利用可能なツール（21 個）

メッセージ

ツール	説明
get_messages	チャットからメッセージを読み込みます（chat_id または message_ids を指定）
send_message	テキスト、HTML／Markdown、インラインキーボード、メディア添付を含むメッセージを送信します
edit_message	メッセージのテキストと添付ファイルを編集します
delete_message	メッセージを削除します
pin_message	チャットでメッセージをピン留めします
unpin_message	現在ピン留めされているメッセージのピン留めを解除します

メディア

ツール	説明
send_media	URL を指定して、写真、動画、音声、またはファイルをアップロードして送信します
send_action	入力中、「写真／動画／音声／ファイルを送信中」のインジケーターを表示するか、既読にします

チャット

ツール	説明
get_bot_info	ボット情報：名前、ID、ユーザー名、説明
get_chats	ボットが参加しているグループチャットの一覧を取得します
get_chat	チャットの詳細情報：参加者、ピン留めされたメッセージ、オーナー
edit_chat	チャット名、説明、アイコンを変更します

メンバー

ツール	説明
get_chat_members	ロール付きでチャットメンバーの一覧を取得します
get_admins	権限付きでチャット管理者の一覧を取得します
set_admin	メンバーに管理者権限を付与します
remove_admin	管理者権限を取り消します
add_members	グループチャットにユーザーを追加します
remove_member	グループチャットからユーザーを削除します

イベント

ツール	説明
get_updates	メッセージ、ボタン操作、新しいダイアログなどの受信イベントを取得します（ロングポーリング）
answer_callback	インラインボタン操作に応答します：通知を表示するか、メッセージを更新します

ボタン（send_message の添付ファイル経由）

次の 5 種類のボタンに対応しています：callback、link、message、request_contact、request_geo_location。

---

使用例

Claude Desktop に接続したら、自然な言葉で指示できます。

「チャット 123456789 に『会議は 10 分後に始まります』とメッセージを送信して」

「チームチャットに承認／却下ボタン付きの承認リクエストを送って」

「お知らせチャットの最新 10 件のメッセージを表示して」

「この写真をチャットに送って：https://example.com/image.jpg」

「営業グループのメンバーは誰？ Alex を管理者にして」

「新着メッセージとボタン操作がないか確認して」

---

設定

環境変数

変数	必須	デフォルト	説明
MAX_TOKEN	✅	—	MAX ボットのトークン
MCP_TRANSPORT	❌	stdio	トランスポート：stdio または http
MCP_PORT	❌	3000	HTTP モードのポート

コマンドラインフラグ

# Local stdio mode (default)
npx @woyax/mcp-max-messenger

# Remote HTTP mode
npx @woyax/mcp-max-messenger --transport http --port 3000

---

アーキテクチャ

2 つの独立したレイヤーで構成され、どちらのモードでもツールは同じように動作します。

src/
├── core/               # Business logic — shared between modes
│   ├── max-client.ts   # MAX API HTTP client
│   ├── types.ts        # TypeScript types for MAX API
│   └── tools/
│       ├── bot.ts      # get_bot_info
│       ├── chats.ts    # get_chats, get_chat, edit_chat, send_action
│       ├── messages.ts # send/get/edit/delete/pin/unpin, send_media
│       ├── members.ts  # get_chat_members, get_admins, set/remove_admin, add/remove_members
│       └── updates.ts  # get_updates, answer_callback
├── transports/         # Transport layer — selected at runtime
│   ├── stdio.ts        # Local mode (Claude Desktop, Cursor)
│   └── http.ts         # Remote mode (Streamable HTTP)
└── index.ts            # Entry point: transport selection

---

MAX API に関する注意事項

• 認証：トークンは Authorization: <token> として渡します。Bearer プレフィックスは不要です。
• ベース URL：https://platform-api.max.ru
• レート制限：1 秒あたり 30 リクエスト
• グループチャット：GET /chats はグループチャットのみを返します
• 個人ダイアログ：get_updates からアクセスできます。返された chat_id をすべての標準ツールで使用します
• メディアのアップロード：2 段階の処理（アップロード → 送信）です。音声／動画のトークンはファイル転送ではなく、アップロードの段階で取得します
• HTTP トランスポート：Streamable HTTP を使用します（MCP SDK 1.10.0 以降、SSE は非推奨です）

MAX API の既知の問題

• remove_admin は、実際には権限を取り消していないのに success: true を返すことがあります。MAX 側のバグとして確認済みです
• open_app ボタンタイプは「Field 'webApp' cannot be null」を返します。MAX API のバグです
• ユーザーがプライバシーモードを有効にしている場合、add_members は add.participant.privacy エラーで失敗することがあります

---

ロードマップ

• n8n 連携を含む VPS での HTTP モードのテスト
• ホスト型 MCP サービス（ローカルにインストールせず、URL で接続）
• リアルタイムのイベント処理に対応する Webhook サポート
• n8n の Webhook ワークフローを使った answer_callback のテスト

---

リンク

• MAX Bot API ドキュメント
• MAX OpenAPI スキーマ
• Model Context Protocol
• npm パッケージ
• ロシア語版 README

---

作者とサポート

Oleg Alekseev が開発しました。ERP／AI 連携アーキテクトです。

• 📧 [email protected] · [email protected]
• 💬 Telegram： @ale_oleg · チャンネル：@woyax_ai
• 💬 MAX：max.ru/id503610654564_biz

ERP、CRM、または MAX と AI エージェントを連携する際にサポートが必要ですか？カスタム MCP サーバー、n8n ワークフロー、AI 自動化については、お問い合わせください。

---

ライセンス

MIT + Commons Clause © Oleg Alekseev

個人および法人の目的で自由に使用できます。ホスト型サービスとして販売するには、作者の許可が必要です。詳しくはLICENSEをご覧ください。