mattermost-mcp

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 <url> | Mattermost API URL (e.g., https://mattermost.example.com/api/v4) | | --token <token> | Mattermost personal access token | | --team-id <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: ``bash 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