Mattermost MCP Server

Features

Topic Monitoring

• Monitor specified channels for messages containing topics of interest

• Run on a configurable schedule (using cron syntax)

• Send notifications when relevant topics are discussed

• Mention you in a specified channel when topics are found

Channel Tools

• `mattermost_list_channels`: List public channels in the workspace

• `mattermost_get_channel_history`: Get recent messages from a channel

Message Tools

• `mattermost_post_message`: Post a new message to a channel

• `mattermost_reply_to_thread`: Reply to a specific message thread

• `mattermost_add_reaction`: Add an emoji reaction to a message

• `mattermost_get_thread_replies`: Get all replies in a thread

Monitoring Tools

• `mattermost_run_monitoring`: Trigger the topic monitoring process immediately

User Tools

• `mattermost_get_users`: Get a list of users in the workspace

• `mattermost_get_user_profile`: Get detailed profile information for a user

Setup

1. Clone this repository:

1. Install dependencies:

1. Configure the server: The repository includes a `config.json` file with placeholder values. For your actual configuration, create a `config.local.json` file (which is gitignored) with your real credentials: ```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 } } ``` This approach keeps your real credentials out of the repository while maintaining the template for others.

2. Build the server:

1. Run the server:

Topic Monitoring Configuration

• `enabled` (boolean): Whether monitoring is enabled

• `schedule` (string): Cron expression for when to check for new messages (e.g., "*/15 * * * *" for every 15 minutes)

• `channels` (string[]): Array of channel names to monitor

• `topics` (string[]): Array of topics to look for in messages

• `messageLimit` (number): Number of recent messages to analyze per check

• `notificationChannelId` (string, optional): Channel ID where notifications will be sent. If not provided, the system will automatically use a direct message channel.

• `userId` (string, optional): Your user ID for mentions in notifications. If not provided, the system will automatically detect the current user.

Running Monitoring Manually

1. **Using the provided scripts**: - `./run-monitoring-http.sh` - Triggers monitoring via HTTP without restarting the server (recommended) - `./run-monitoring.sh` - Starts a new server instance with monitoring enabled - `./trigger-monitoring.sh` - Runs the monitoring process and exits (useful for cron jobs) - `./view-channel-messages.js <channel-name> [count]` - View the last messages in a channel - `./analyze-channel.js <channel-name> [count]` - Analyze message statistics in a channel - `./get-last-message.js <channel-name>` - Get the last message from a channel

2. **Using the command-line interface (CLI)**: - While the server is running, simply type one of these commands in the terminal: - `run` - Run the monitoring process - `monitor` - Same as `run` - `check` - Same as `run` - Other available commands: - `help` - Show available commands - `exit` - Shutdown the server

3. **Using the MCP tool**: - Use the `mattermost_run_monitoring` tool through the MCP interface - This will immediately check all configured channels for your topics of interest

4. **Using the command-line flags**: - Start the server with the `--run-monitoring` flag: ```bash npm start -- --run-monitoring ``` - This will run the monitoring process immediately after the server starts - Add `--exit-after-monitoring` to exit after the monitoring process completes: ```bash npm start -- --run-monitoring --exit-after-monitoring ``` - This is useful for running the monitoring process from cron jobs

Tool Details

Channel Tools

`mattermost_list_channels`

• List public channels in the workspace

• Optional inputs: - `limit` (number, default: 100, max: 200): Maximum number of channels to return - `page` (number, default: 0): Page number for pagination

• Returns: List of channels with their IDs and information

`mattermost_get_channel_history`

• Get recent messages from a channel

• Required inputs: - `channel_id` (string): The ID of the channel

• Optional inputs: - `limit` (number, default: 30): Number of messages to retrieve - `page` (number, default: 0): Page number for pagination

• Returns: List of messages with their content and metadata

Message Tools

`mattermost_post_message`

• Post a new message to a Mattermost channel

• Required inputs: - `channel_id` (string): The ID of the channel to post to - `message` (string): The message text to post

• Returns: Message posting confirmation and ID

`mattermost_reply_to_thread`

• Reply to a specific message thread

• Required inputs: - `channel_id` (string): The channel containing the thread - `post_id` (string): ID of the parent message - `message` (string): The reply text

• Returns: Reply confirmation and ID

`mattermost_add_reaction`

• Add an emoji reaction to a message

• Required inputs: - `channel_id` (string): The channel containing the message - `post_id` (string): Message ID to react to - `emoji_name` (string): Emoji name without colons

• Returns: Reaction confirmation

`mattermost_get_thread_replies`

• Get all replies in a message thread

• Required inputs: - `channel_id` (string): The channel containing the thread - `post_id` (string): ID of the parent message

• Returns: List of replies with their content and metadata

User Tools

`mattermost_get_users`

• Get list of workspace users with basic profile information

• Optional inputs: - `limit` (number, default: 100, max: 200): Maximum users to return - `page` (number, default: 0): Page number for pagination

• Returns: List of users with their basic profiles

`mattermost_get_user_profile`

• Get detailed profile information for a specific user

• Required inputs: - `user_id` (string): The user's ID

• Returns: Detailed user profile information

Usage with Claude Desktop

Troubleshooting

1. Your personal access token has the necessary permissions

2. The token is correctly copied to your configuration

3. The Mattermost URL and team ID are correct

HTTP Endpoints

• **Run Monitoring**: `http://localhost:3456/run-monitoring` - Triggers the monitoring process immediately - Returns JSON response with success/error information

• **Check Status**: `http://localhost:3456/status` - Returns information about the server and monitoring status - Useful for health checks

Utility Scripts

run-monitoring-http.sh

• Doesn't restart the server

• Doesn't interfere with the scheduled monitoring

• Works reliably from any terminal

view-channel-messages.js

• Channel information (name, purpose, total message count)

• The most recent messages with timestamps and usernames

• If the channel doesn't exist, it will list all available channels

analyze-channel.js

• Channel information and metadata

• Total message count (including system messages)

• Breakdown of user messages vs. system messages

• Message count by user

• The most recent messages in the channel

get-last-message.js

• The sender's user ID and username

• The timestamp of the message

• The full message content

License