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 集成 和 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 安装会删除没有项目引用的版本。
• 如果下载失败，错误信息会包含原因和作为备用方案的手动命令，参见浏览器登录问题。
• 在缺少 Chromium 系统库的 Linux 上，需要运行一次 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：短期锁定文件，可让多个服务进程共用一个登录窗口。
• tmp/：Chromium 下载临时文件，安装后会删除。

如果 ~/.config 或你的主目录属于其他用户，或者在没有粘滞位的情况下可由组或其他用户写入，服务将拒绝使用该目录。请参阅浏览器登录问题中的 [STATE_DIRECTORY_UNSAFE]。

登录窗口的安全性

• Chromium 窗口会启用 Chromium 沙箱，因为它会渲染其他用户编写的 Mattermost 内容。只有当你的系统无法使用沙箱（[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 和其他客户端会共用一个令牌文件和一个登录窗口。如果多个客户端同时需要登录，只会打开一个窗口，所有等待中的调用都会在你登录后继续执行。

后台主题监控不会打开登录窗口。当服务启动时没有已保存的会话：

• 如果未设置 monitoring.userId 或 monitoring.notificationChannelId，监控器无法查找这些信息，其计划任务也不会启动。请调用 mattermost_run_monitoring：如果需要，它会先登录，然后启动计划任务并运行一次监控。通过其他工具登录不会启动计划任务，因此之后请调用 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 服务。其他服务的令牌文件会被忽略。比较前会规范化地址，因此 /api/v4、末尾的斜杠和主机名的大小写均不影响比较结果。
• 如果具有不同 MATTERMOST_URL 值的客户端同时登录，等待中的调用会收到 LOGIN_NOT_COMPLETED，只有再次调用工具时才会打开第二个服务的窗口。第二个服务的令牌会替换第一个服务的令牌，而第一个服务会在下次调用时重新打开窗口。
• 请勿为服务启用 DEBUG=pw:*：Playwright 调试输出会打印 Cookie。
• 不支持 Windows。

配置

服务支持多种配置方式，优先级如下（从高到低）：

1. CLI 参数（--url、--token、--team-id）
2. 环境变量（MATTERMOST_URL、MATTERMOST_TOKEN、MATTERMOST_TEAM_ID）
3. config.local.json（用于本地覆盖配置，已加入 gitignore）
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（已加入 gitignore），或使用 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	列出工作区中的频道（公开频道、私人频道和私信）
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. 前往 Network 标签页
4. 刷新页面
5. 查找包含 teams/ 的 API 调用——ID 位于 URL 中

或者使用 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)

请确保已通过 CLI 参数、环境变量或配置文件提供 Mattermost URL 和团队 ID。无需提供令牌：没有令牌时，服务会使用浏览器登录。

权限错误

请确认：

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 工具进行登录。

[STATE_DIRECTORY_UNSAFE]：~/.config/mattermost-mcp 或其子目录是符号链接、不是目录或属于其他用户；或者 ~/.config 或你的主目录属于其他用户，或可由组用户或其他用户写入。请按错误文本中的说明修复（例如 chmod go-w ~/.config），然后再次调用工具。

[REQUEST_CANCELLED]：客户端在登录窗口打开期间取消了调用，例如因超时而取消。请求尚未发送，因此不会重复发布任何内容。登录会在窗口中继续，请在登录后再次调用工具。

许可证

MIT 许可证