Mattermost Mcp

Mattermost MCP サーバー

Mattermost API 用の MCP サーバーです。Claude やその他の MCP クライアントが Mattermost ワークスペースとやり取りできるようにします。

クイックスタート

npx を使用する（推奨）

npx @conarti/mattermost-mcp --help

環境変数を使用する

MATTERMOST_URL=https://your-mattermost.com/api/v4 \
MATTERMOST_TOKEN=your-token \
MATTERMOST_TEAM_ID=your-team-id \
npx @conarti/mattermost-mcp

CLI 引数を使用する

npx @conarti/mattermost-mcp \
  --url https://your-mattermost.com/api/v4 \
  --token your-token \
  --team-id your-team-id

インストール

オプション 1：npx（インストール不要）

npx @conarti/mattermost-mcp

オプション 2：グローバルインストール

npm install -g @conarti/mattermost-mcp
mattermost-mcp --help

オプション 3：クローンしてビルド

git clone https://github.com/conarti/mattermost-mcp.git
cd mattermost-mcp
npm install
npm run build
npm start

ブラウザーでサインインする（トークン不要）

MATTERMOST_TOKEN は任意です。トークンを指定しない場合、サーバーは表示される Chromium ウィンドウを通じて Mattermost にサインインし、セッショントークンを保持します。MATTERMOST_TOKEN を設定すると、サーバーは従来どおり（静的モード）動作します。ブラウザーウィンドウは表示されず、Chromium もダウンロードされず、~/.config/mattermost-mcp も作成されません。

初回サインイン

1. トークンを指定せず、MATTERMOST_URL と MATTERMOST_TEAM_ID のみでサーバーを設定します（下記のClaude Code Integrationとopencodeを参照）。
2. Mattermost ツールを呼び出します。Mattermost のログインページを表示した Chromium ウィンドウが開きます。
3. いつもの方法（パスワード、SSO、MFA）でサインインします。制限時間は 5 分です。
4. セッションが有効になると、ウィンドウが自動的に閉じ、ツール呼び出しの結果が返されます。

呼び出しの処理中、サーバーは 10 秒ごとに進行状況の通知を送信するため、MCP の進行状況を表示するクライアントでは現在のステップを確認できます。ウィンドウが開くのはツール呼び出し時のみです。サーバーの起動時やバックグラウンド監視中に開くことはありません。

Chromium は自動的にダウンロードされます

手動でインストールする必要はありません。

• 初回サインイン時に、サーバーは Playwright 1.63.0 用の Chromium と ffmpeg を（macOS arm64 では約 183 MiB）~/.config/mattermost-mcp/browsers にダウンロードします。クライアントには進行状況が Downloading Chromium for Mattermost sign-in: 40% of 182.1 MiB と表示され、続いてダウンロードされる小さな ffmpeg アーカイブについては Downloading Chromium for Mattermost sign-in: FFmpeg 50% of 1 MiB と表示されます。
• 初回の呼び出しには時間がかかります。ダウンロードの制限時間は 10 分で、サインインの 5 分間はダウンロード完了後に始まります。
• このパッケージを別の Playwright バージョンを使用するバージョンに更新すると、対応する Chromium ビルドも同じ方法でダウンロードされます。
• プロキシ経由の場合、またはダウンロードミラーを使用する場合は、MCP サーバーエントリの env に HTTPS_PROXY、HTTP_PROXY、NO_PROXY、PLAYWRIGHT_DOWNLOAD_HOST、または PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT を設定してください。
• 共通の Playwright キャッシュ（macOS では ~/Library/Caches/ms-playwright）は使用されません。他のプロジェクトに参照されていないビルドは、他のプロジェクトでの Playwright のインストール時に削除されるためです。
• ダウンロードに失敗した場合、エラーに理由と代替手段としての手動コマンドが表示されます。ブラウザーでのサインインに関する問題を参照してください。
• Linux で Chromium のシステムライブラリがない場合は、初回に限り install-deps コマンドが必要です。ブラウザーでのサインインに関する問題を参照してください。
• このパッケージは常に最新の状態に保ってください。各リリースでは Playwright のバージョンが固定されており、新しいバージョンではセキュリティ修正を含む Chromium ビルドが提供されます。
• PLAYWRIGHT_DOWNLOAD_HOST には https:// を使用し、ダウンロード時の TLS 証明書のチェックを無効にしないでください（たとえば NODE_TLS_REJECT_UNAUTHORIZED=0 を設定しないでください）。ダウンロードした Chromium は後で Mattermost のセッションを保持するためです。

各データの保存場所

すべてのデータは ~/.config/mattermost-mcp/（権限 0700）に保存されます。

• browsers/：サインインウィンドウ用の Chromium ビルドです。
• profile/：Mattermost のセッションが保存された Chromium プロファイルです。Cookie が暗号化されていないため、トークンと同じように機密性の高いデータです。ドットファイルの同期やバックアップの対象から除外してください。
• token：サーバーアドレスに紐付けられたセッショントークンです（権限 0600）。
• login.lock と login.lock.break：複数のサーバープロセスで 1 つのサインインウィンドウを共有するための短期間有効なロックファイルです。
• tmp/：Chromium のダウンロード時に使用する一時ファイルです。インストール後に削除されます。

~/.config またはホームディレクトリの所有者が別のユーザーである場合、あるいはスティッキービットなしでグループまたはその他のユーザーに書き込み権限がある場合、サーバーはそのディレクトリの使用を拒否します。詳しくは、ブラウザーのサインインに関する問題の [STATE_DIRECTORY_UNSAFE] を参照してください。

サインインウィンドウのセキュリティ

• 他のユーザーが作成した Mattermost のコンテンツを表示するため、Chromium ウィンドウでは Chromium サンドボックスが有効になっています。お使いのシステムでサンドボックスを利用できない場合（[BROWSER_SANDBOX_UNAVAILABLE]）に限り、MCP サーバーのエントリの env に MATTERMOST_MCP_DISABLE_CHROMIUM_SANDBOX=1 を設定してください。この場合、ウィンドウを開くたびにサーバーが警告をログに記録します。
• MATTERMOST_URL には https:// アドレスを使用してください。http:// と localhost、127.0.0.1、[::1] 以外のホストを組み合わせると、サインインウィンドウに入力したパスワードとセッショントークンが暗号化されずに送信されることを示す警告が、サーバーの起動時にログに記録されます。

セッションのリセット

セッションのみを削除します（次のツール呼び出しで、再びサインインウィンドウが開きます）。

rm -rf ~/.config/mattermost-mcp/profile ~/.config/mattermost-mcp/token

Chromium を含めてすべて削除します（次回のサインイン時に再ダウンロードされます）。

rm -rf ~/.config/mattermost-mcp

どちらのコマンドも、サインインウィンドウが開いている間に実行しても安全です。

複数のクライアント

Claude Code、opencode、その他のクライアントは、同じマシン上で 1 つのトークンファイルと 1 つのサインインウィンドウを共有します。複数のクライアントで同時にサインインが必要になった場合、ウィンドウは 1 つだけ開き、サインインが完了すると待機中のすべての呼び出しが続行されます。

バックグラウンドのトピック監視では、ウィンドウは開きません。保存済みのセッションがない状態でサーバーが起動した場合：

• monitoring.userId または monitoring.notificationChannelId が設定されていないと、監視機能はそれらを検索できず、スケジュールも開始されません。mattermost_run_monitoring を呼び出してください。必要に応じてサインインし、スケジュールを開始して、監視を 1 回実行します。別のツールからサインインしてもスケジュールは開始されないため、その後に mattermost_run_monitoring を呼び出すか、サーバーを再起動してください。
• 両方が設定されている場合、スケジュールはすぐに開始されます。最初のサインイン前に実行された監視はスキップされ、そのことがログに [AUTHENTICATION_REQUIRED] として記録されます。

opencode

トークンを指定しない opencode エントリの例：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mattermost": {
      "type": "local",
      "command": ["npx", "-y", "@conarti/mattermost-mcp@latest"],
      "environment": {
        "MATTERMOST_URL": "https://your-mattermost.com/api/v4",
        "MATTERMOST_TEAM_ID": "your-team-id"
      },
      "timeout": 360000
    }
  },
  "experimental": {
    "mcp_timeout": 360000
  }
}

クライアントのタイムアウト

最初のツール呼び出しには数分かかることがあります。Chromium のダウンロード後、サインインに最大 5 分かかります。10 秒ごとに進行状況の通知が送られます。progressToken を渡し、進行状況の通知を受け取るたびにタイムアウトをリセットするクライアントでは、この通知によって呼び出しが継続されます。

• opencode：上記の例のように、mcp.mattermost.timeout と experimental.mcp_timeout を 360000（6 分）に設定してください。opencode の一部のバージョンでは、進行状況の通知で延長されない固定のリクエストタイムアウトが適用されます。
• progressToken を渡さないクライアントでは、Chromium のダウンロード中に最初の呼び出しがキャンセルされることがあります。その場合、ダウンロードは停止し、次の呼び出しで最初からやり直されます。クライアントのタイムアウトを延長するか、ブラウザーのサインインに関する問題に記載されている手動インストールコマンドを一度実行してください。

制限事項

• オペレーティングシステムのユーザーごとに、Mattermost サーバーは1つです。別のサーバーのトークンファイルは無視されます。比較の前にアドレスは正規化されるため、/api/v4、末尾のスラッシュ、ホスト名の大文字と小文字は比較に影響しません。
• 異なるMATTERMOST_URLのクライアントが同時にサインインすると、待機中の呼び出しはLOGIN_NOT_COMPLETEDを受け取り、2つ目のサーバーのウィンドウは、ツールを再度呼び出したときにのみ開きます。2つ目のサーバーのトークンが1つ目のサーバーのトークンに置き換わり、1つ目のサーバーは次の呼び出し時に再びウィンドウを開きます。
• サーバーでDEBUG=pw:*を有効にしないでください。Playwrightのデバッグ出力にはCookieが表示されます。
• Windowsはサポートされていません。

設定

サーバーでは、次の優先順位（高い順）で複数の設定方法をサポートしています。

1. CLI引数（--url、--token、--team-id）
2. 環境変数（MATTERMOST_URL、MATTERMOST_TOKEN、MATTERMOST_TEAM_ID）
3. config.local.json（ローカルの上書き設定用、Gitで無視されます）
4. config.json（デフォルト設定）

CLI引数

引数	説明
--url <url>	Mattermost APIのURL（例：https://mattermost.example.com/api/v4）
--token <token>	Mattermostの個人用アクセストークン
--team-id <id>	MattermostのチームID
--run-monitoring	起動時にトピック監視をすぐに実行します
--exit-after-monitoring	監視の実行後に終了します（--run-monitoringと併用）
--help	ヘルプメッセージを表示します

環境変数

変数	説明
MATTERMOST_URL	Mattermost APIのURL
MATTERMOST_TOKEN	Mattermostの個人用アクセストークン（省略可能：指定しない場合、サーバーはブラウザーでサインインを使用します）
MATTERMOST_TEAM_ID	MattermostのチームID
HTTPS_PROXY、HTTP_PROXY、NO_PROXY	ブラウザーでサインインする際のChromium自動ダウンロード用プロキシ
PLAYWRIGHT_DOWNLOAD_HOST、PLAYWRIGHT_DOWNLOAD_CONNECTION_TIMEOUT	Chromium自動ダウンロード用のミラーと接続タイムアウト

設定ファイル

config.local.json（Gitで無視されます）を作成するか、config.jsonを使用します。

{
  "mattermostUrl": "https://your-mattermost-instance.com/api/v4",
  "token": "your-personal-access-token",
  "teamId": "your-team-id",
  "monitoring": {
    "enabled": false,
    "schedule": "*/15 * * * *",
    "channels": ["town-square", "off-topic"],
    "topics": ["tv series", "champions league"],
    "messageLimit": 50
  }
}

Claude Codeとの統合

Claude CodeのMCP設定（~/.claude/claude_desktop_config.jsonまたはclaude mcp add経由）に追加します。

{
  "mcpServers": {
    "mattermost": {
      "command": "npx",
      "args": ["-y", "@conarti/mattermost-mcp@latest"],
      "env": {
        "MATTERMOST_URL": "https://your-mattermost.com/api/v4",
        "MATTERMOST_TOKEN": "your-token",
        "MATTERMOST_TEAM_ID": "your-team-id"
      }
    }
  }
}

または、設定ファイルを使用します。

{
  "mcpServers": {
    "mattermost": {
      "command": "node",
      "args": ["/path/to/mattermost-mcp/build/index.js"]
    }
  }
}

または、トークンを指定せずにブラウザーでサインインします。

{
  "mcpServers": {
    "mattermost": {
      "command": "npx",
      "args": ["-y", "@conarti/mattermost-mcp@latest"],
      "env": {
        "MATTERMOST_URL": "https://your-mattermost.com/api/v4",
        "MATTERMOST_TEAM_ID": "your-team-id"
      }
    }
  }
}

最初のツール呼び出しでサインインウィンドウが開き、初回のサインイン時にChromiumがダウンロードされます。

機能

チャンネルツール

ツール	説明
mattermost_list_channels	ワークスペース内のチャンネル（パブリック、プライベート、DM）を一覧表示します
mattermost_get_channel_history	フィルターオプションを指定して、チャンネルのメッセージを取得します

mattermost_list_channelsのオプション

• limit（デフォルト：100）：返すチャンネルの最大数
• page（デフォルト：0）：ページネーションのページ番号
• include_private（デフォルト：false）：trueの場合、プライベートチャンネルとダイレクトメッセージ（DM）を含むすべてのチャンネルを返します

mattermost_get_channel_historyのオプション

• channel_id（必須）：チャンネルのID
• limit：取得するメッセージ数。指定しない場合、または0の場合、すべてのメッセージを返します
• page（デフォルト：0）：ページネーションのページ番号（limitが0より大きい場合のみ使用）
• since_date：この日付以降のメッセージを取得するISO 8601形式の日付（例：「2025-01-15」）
• before_date：この日付より前のメッセージを取得するISO 8601形式の日付。日付範囲を指定するにはsince_dateと併用します
• before_post_id：この投稿IDより前のメッセージを取得します（カーソルページネーション）
• after_post_id：この投稿IDより後のメッセージを取得します（カーソルページネーション）

例：

// Get ALL messages from a channel
{ "channel_id": "abc123" }

// Get last 50 messages
{ "channel_id": "abc123", "limit": 50 }

// Get all messages from December 18, 2025
{ "channel_id": "abc123", "since_date": "2025-12-18", "before_date": "2025-12-19" }

// Get messages from a specific date onwards
{ "channel_id": "abc123", "since_date": "2025-12-15" }

メッセージツール

ツール	説明
mattermost_post_message	チャンネルに新しいメッセージを投稿します
mattermost_reply_to_thread	特定のメッセージスレッドに返信します
mattermost_add_reaction	メッセージに絵文字リアクションを追加します
mattermost_get_thread_replies	スレッド内のすべての返信を取得します
mattermost_get_post	IDで単一のメッセージを取得します（テキスト、作成者、チャンネル、作成・編集時刻、スレッドのルート、添付ファイル）
mattermost_edit_post	既存のメッセージのテキストを置き換え、id、message、edit_atを返します

mattermost_get_channel_historyおよびmattermost_get_thread_replies（root_postを含む）で取得した添付ファイル付き投稿には、file_idsとfiles（id、name、extension、size、mime_type、および画像の場合はwidth／height）が含まれます。添付ファイルのない投稿には、どちらのフィールドも含まれません。

mattermost_edit_postはpost_idとmessageを受け取ります。Mattermostでは、編集された投稿はチャンネル内の全員に「編集済み」と表示されます。投稿者、または他のユーザーの投稿を編集する権限を持つユーザーのみが編集できます。403エラーの場合は、そのヒントを含むサーバーのテキストを返し、その他のエラー（編集可能な時間制限を過ぎた場合の400など）では、サーバーのテキストをそのまま返します。どちらのツールも、リクエストを送信する前に、26文字のMattermost IDではないpost_idを拒否します。

ファイルツール

ツール	説明
mattermost_get_file_info	添付ファイルのメタデータ（名前、拡張子、サイズ、MIMEタイプ、画像サイズ、投稿ID）を取得します
mattermost_download_file	添付ファイルをローカルディスクにダウンロードし、絶対パスとメタデータを返します

mattermost_download_fileのオプション

• file_id（必須）：投稿のfile_idsまたはfilesにあるファイルのID
• output_path：ファイルの保存先
  • 未設定の場合：システムの一時ディレクトリにmattermost-mcp/{file_id}_{name}として保存します
  • 既存のディレクトリ、または末尾が/か\のパスの場合：元の名前でその中にファイルを保存し、存在しないディレクトリは作成します
  • その他のパスの場合：ファイルパスとして扱い、存在しない親ディレクトリは作成します
  • 先頭の~はホームディレクトリに展開されます（~userは展開されません）。相対パスはサーバーの作業ディレクトリを基準に解決されます
  • 保存先に同名のファイルがすでに存在する場合は上書きされます
• inline（デフォルト：false）：画像をMCP画像コンテンツとしても返します。1 MB以下のimage/png、image/jpeg、image/gif、image/webpのみインラインで返されます。それ以外の場合、レスポンスにinline_skipped_reasonが含まれます

例：

• 一時ディレクトリに保存します：{ "file_id": "abcdefghijklmnopqrstuvwxyz" }
• ~/Downloadsに保存し、小さな画像をインラインで表示します：{ "file_id": "abcdefghijklmnopqrstuvwxyz", "output_path": "~/Downloads/", "inline": true }

ユーザーツール

ツール	説明
mattermost_get_users	ワークスペース内のユーザー一覧を取得します
mattermost_get_user_profile	ユーザーの詳細なプロフィール情報を取得します

監視ツール

ツール	説明
mattermost_run_monitoring	トピック監視をただちに実行します

トピック監視

このサーバーには、次の機能を備えたトピック監視システムが含まれています。

• 指定したチャンネルを監視し、関心のあるトピックを含むメッセージを検出します
• 設定可能なスケジュール（cron構文を使用）で実行します
• 関連するトピックが話題になったときに通知を送信します

設定

{
  "monitoring": {
    "enabled": true,
    "schedule": "*/15 * * * *",
    "channels": ["general", "random"],
    "topics": ["important", "urgent"],
    "messageLimit": 50,
    "notificationChannelId": "optional-channel-id",
    "userId": "optional-user-id"
  }
}

監視を手動で実行する

# Run monitoring and continue server
mattermost-mcp --run-monitoring

# Run monitoring and exit (useful for cron jobs)
mattermost-mcp --run-monitoring --exit-after-monitoring

認証情報の取得

MattermostのURL

Mattermost APIのURLは通常、https://your-mattermost-domain.com/api/v4です。

パーソナルアクセストークン

1. アカウント設定 > セキュリティ > パーソナルアクセストークンに移動します
2. トークンを作成をクリックします
3. 説明を入力して作成します
4. トークンをコピーします（再表示されません）

チームID

1. Mattermostでチームに移動します
2. ブラウザーの開発者ツール（F12）を開きます
3. ネットワークタブに移動します
4. ページを更新します
5. teams/を含むAPI呼び出しを探します。URL内にIDがあります

または、Mattermost APIを使用します。

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-mattermost.com/api/v4/teams

トラブルシューティング

設定不足エラー

Missing required configuration:
  - mattermostUrl (--url or MATTERMOST_URL)
  - teamId (--team-id or MATTERMOST_TEAM_ID)

Mattermost の URL とチーム ID を、CLI 引数、環境変数、または設定ファイルで指定していることを確認してください。トークンは必須ではありません。トークンがない場合、サーバーはブラウザーサインインを使用します。

権限エラー

次の点を確認してください。

1. Mattermost ユーザーに必要な権限があること。これは、パーソナルアクセストークンの所有者、またはブラウザーウィンドウでサインインしたユーザーです。
2. トークンを使用する場合、正しく設定されていること。
3. Mattermost の URL とチーム ID が正しいこと。

ブラウザーサインインで別のユーザーとしてサインインするには、セッションをリセットしてから、もう一度ツールを呼び出してください。

ブラウザーサインインの問題

エラーメッセージは、角括弧で囲まれたコードから始まります。

[BROWSER_INSTALLATION_FAILED]：Chromium の自動ダウンロードに失敗しました。エラーには、プロキシやネットワークのエラーなど、理由が記載されています。原因を解消して、もう一度ツールを呼び出してください。代替手段として、Chromium を一度手動でインストールしてください。

PLAYWRIGHT_BROWSERS_PATH=~/.config/mattermost-mcp/browsers npx [email protected] install chromium --no-shell

このコマンドを手動で実行すると、枠で囲まれた WARNING: It looks like you are running 'npx playwright install' without first installing your project's dependencies が表示されますが、これは想定内なので無視できます。

エラーにアクティブな __dirlock が記載されている場合は、別のクライアントが開始した場合など、別の Chromium のインストールが実行中です。完了するまで待ってから、もう一度ツールを呼び出してください。インストールが実行中でない場合は、クラッシュ後にファイルが残っています。エラーテキストに記載されたコマンドで削除できます。

[BROWSER_SYSTEM_DEPENDENCIES_MISSING]（Linux）：Chromium はダウンロードされましたが、システムライブラリがないため起動できません。次のものを一度インストールしてください。

sudo npx [email protected] install-deps chromium

[BROWSER_SANDBOX_UNAVAILABLE]（Linux）：権限のないユーザーの名前空間が無効になっている場合や、サーバーがそのような名前空間を利用できないコンテナー内で実行されている場合など、Chromium のサンドボックスを起動できません。可能であれば、ご使用のユーザーに対してサンドボックスを有効にしてください。それが不可能な場合に限り、MCP サーバーのエントリの env に MATTERMOST_MCP_DISABLE_CHROMIUM_SANDBOX=1 を設定し、もう一度ツールを呼び出してください。

[LOGIN_WINDOW_CLOSED]、[LOGIN_TIMEOUT]、[LOGIN_NOT_COMPLETED]：ウィンドウが閉じられた、サインインに 5 分以上かかった、または別のクライアントでのサインインがセッションなしで終了しました。もう一度ツールを呼び出して、ウィンドウを開いてください。

[LOGIN_PROFILE_BUSY]：別の Chromium ウィンドウがサインインプロファイルを使用しています。もう一方の Mattermost サインインウィンドウを閉じてから、もう一度ツールを呼び出してください。

監視ログの [AUTHENTICATION_REQUIRED]：バックグラウンド監視ではサインインウィンドウは開きません。Mattermost のツールを任意に 1 つ呼び出して、サインインしてください。

[STATE_DIRECTORY_UNSAFE]：~/.config/mattermost-mcp またはそのサブディレクトリがシンボリックリンクである、ディレクトリではない、別のユーザーの所有である、あるいは ~/.config またはホームディレクトリが別のユーザーの所有であるか、グループまたはその他のユーザーが書き込み可能になっています。エラーテキストの指示に従って修正し（たとえば chmod go-w ~/.config）、もう一度ツールを呼び出してください。

[REQUEST_CANCELLED]：サインインウィンドウが開いている間に、タイムアウトなどを理由にクライアントが呼び出しをキャンセルしました。リクエストは送信されていないため、二重に投稿されることはありません。ウィンドウではサインインが続行されるので、サインイン後にもう一度ツールを呼び出してください。

ライセンス

MIT License