Content
# Mattermost MCP Server
MCP Server for the Mattermost API, enabling Claude and other MCP clients to interact with Mattermost workspaces.
## Features
This MCP server provides tools for interacting with Mattermost, including:
### Topic Monitoring
The server includes a topic monitoring system that can:
- 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:
```bash
git clone https://github.com/yourusername/mattermost-mcp.git
cd mattermost-mcp
```
2. Install dependencies:
```bash
npm install
```
3. 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.
4. Build the server:
```bash
npm run build
```
5. Run the server:
```bash
npm start
```
## Topic Monitoring Configuration
The monitoring system can be configured with the following options:
- `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.
To enable monitoring, set `enabled` to `true` in your `config.local.json` file.
### Running Monitoring Manually
You can trigger the monitoring process manually in several ways:
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
Add the following to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"mattermost": {
"command": "node",
"args": [
"/path/to/mattermost-mcp/build/index.js"
]
}
}
}
```
## Troubleshooting
If you encounter permission errors, verify that:
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
The server exposes HTTP endpoints for remote control:
- **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
You can use these endpoints with curl or any HTTP client:
```bash
# Trigger monitoring
curl http://localhost:3456/run-monitoring
# Check status
curl http://localhost:3456/status
```
## Utility Scripts
### run-monitoring-http.sh
This script triggers the monitoring process via the HTTP endpoint:
```bash
./run-monitoring-http.sh
```
This is the recommended way to trigger monitoring manually as it:
- Doesn't restart the server
- Doesn't interfere with the scheduled monitoring
- Works reliably from any terminal
### view-channel-messages.js
This script allows you to view the most recent messages in any channel:
```bash
# View messages in a channel (channel name is required)
node view-channel-messages.js <channel-name>
# View a specific number of messages
node view-channel-messages.js <channel-name> <message-count>
# Example: View the last 10 messages in a channel
node view-channel-messages.js general 10
```
The script will display:
- 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
This script provides detailed statistics about messages in a channel:
```bash
# Analyze messages in a channel (channel name is required)
node analyze-channel.js <channel-name>
# Analyze a specific number of messages
node analyze-channel.js <channel-name> <message-count>
# Example: Analyze the last 50 messages in a channel
node analyze-channel.js general 50
```
The script will display:
- 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
This script retrieves only the most recent message from a channel:
```bash
# Get the last message from a channel (channel name is required)
node get-last-message.js <channel-name>
# Example: Get the last message from the general channel
node get-last-message.js general
```
The script will display:
- The sender's user ID and username
- The timestamp of the message
- The full message content
## License
This MCP server is licensed under the MIT License.
