Mattermost MCP Server

MCP Server for the Mattermost API, enabling Claude and other MCP clients to interact with Mattermost workspaces.

Quick Start

Using npx (recommended)

npx @conarti/mattermost-mcp --help

Using environment variables

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

Using CLI arguments

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

Installation

Option 1: npx (no installation needed)

npx @conarti/mattermost-mcp

Option 2: Global installation

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

Option 3: Clone and build

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

Configuration

The server supports multiple configuration methods with the following priority (highest to lowest):

1. CLI arguments (--url, --token, --team-id)
2. Environment variables (MATTERMOST_URL, MATTERMOST_TOKEN, MATTERMOST_TEAM_ID)
3. config.local.json (for local overrides, gitignored)
4. config.json (default configuration)

CLI Arguments

Argument	Description
--url	Mattermost API URL (e.g., https://mattermost.example.com/api/v4)
--token	Mattermost personal access token
--team-id	Mattermost team ID
--run-monitoring	Run topic monitoring immediately on startup
--exit-after-monitoring	Exit after running monitoring (use with --run-monitoring)
--help	Show help message

Environment Variables

Variable	Description
MATTERMOST_URL	Mattermost API URL
MATTERMOST_TOKEN	Mattermost personal access token
MATTERMOST_TEAM_ID	Mattermost team ID

Configuration File

Create config.local.json (gitignored) or use 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 Integration

Add to your Claude Code MCP settings (~/.claude/claude_desktop_config.json or via 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"
      }
    }
  }
}

Or using a config file:

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

Features

Channel Tools

Tool	Description
mattermost_list_channels	List channels in the workspace (public, private, and DMs)
mattermost_get_channel_history	Get messages from a channel with filtering options

mattermost_list_channels Options

• limit (default: 100): Maximum number of channels to return
• page (default: 0): Page number for pagination
• include_private (default: false): If true, returns all channels including private channels and direct messages (DMs)

mattermost_get_channel_history Options

• channel_id (required): The ID of the channel
• limit: Number of messages to retrieve. If not specified or 0, returns ALL messages
• page (default: 0): Page number for pagination (only used when limit > 0)
• since_date: ISO 8601 date to get messages after (e.g., "2025-01-15")
• before_date: ISO 8601 date to get messages before. Use with since_date for date ranges
• before_post_id: Get messages before this post ID (cursor pagination)
• after_post_id: Get messages after this post ID (cursor pagination)

Examples:

// 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" }

Message Tools

Tool	Description
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

User Tools

Tool	Description
mattermost_get_users	Get a list of users in the workspace
mattermost_get_user_profile	Get detailed profile information for a user

Monitoring Tools

Tool	Description
mattermost_run_monitoring	Trigger topic monitoring immediately

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

Configuration

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

Running Monitoring Manually

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

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

Getting Your Credentials

Mattermost URL

Your Mattermost API URL is typically: https://your-mattermost-domain.com/api/v4

Personal Access Token

1. Go to Account Settings > Security > Personal Access Tokens
2. Click Create Token
3. Give it a description and create
4. Copy the token (it won't be shown again)

Team ID

1. Go to your team in Mattermost
2. Open browser developer tools (F12)
3. Go to Network tab
4. Refresh the page
5. Look for API calls containing teams/ — the ID is in the URL

Or use the Mattermost API:

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

Troubleshooting

Missing Configuration Error

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

Make sure you've provided all required configuration via CLI arguments, environment variables, or config file.

Permission Errors

Verify that:

1. Your personal access token has the necessary permissions
2. The token is correctly set
3. The Mattermost URL and team ID are correct

License

MIT License