adeg/mattermost-mcp

Mattermost MCP Server

A production-ready Model Context Protocol (MCP) server for Mattermost integration. Built with FastAPI and FastMCP, this server exposes Mattermost functionality through 10 MCP tools and includes an intelligent topic monitoring system with Claude AI-powered semantic analysis.

Table of Contents

• Overview
• Available MCP Tools
• Installation
• Configuration
• Docker Deployment
• Nomad Deployment
• Configuring Topic Monitoring
• Development
• Project Structure
• Solution Architecture
• License

Overview

The Mattermost MCP Server enables AI assistants and LLM-powered applications to interact with Mattermost workspaces through the Model Context Protocol. It provides a comprehensive set of tools for channel management, messaging, user operations, and automated topic monitoring.

Key Features

• 10 MCP Tools for complete Mattermost interaction (channels, messages, users, monitoring)
• Topic Monitoring with scheduled polling and intelligent notifications
• Claude AI Integration for semantic topic matching (with keyword fallback)
• Production-Ready with Docker and Nomad deployment configurations
• Async Architecture using FastAPI for high-performance I/O operations
• Structured Logging with JSON output for observability
• Health Endpoints for orchestration and load balancer integration

Technology Stack

Available MCP Tools

The server exposes 10 MCP tools organized into four categories:

Channel Tools

mattermost_list_channels

List all public channels in the Mattermost workspace with pagination support.

Returns:

{
  "channels": [
    {
      "id": "channel-id",
      "name": "general",
      "display_name": "General",
      "type": "O",
      "purpose": "Channel purpose",
      "header": "Channel header",
      "total_msg_count": 1234
    }
  ],
  "total_count": 50,
  "page": 0,
  "per_page": 100
}

mattermost_get_channel_history

Retrieve recent messages from a specific channel.

Returns:

{
  "posts": [
    {
      "id": "post-id",
      "user_id": "user-id",
      "message": "Hello, world!",
      "create_at": "2024-11-04T14:06:82.000Z",
      "reply_count": 3,
      "root_id": null
    }
  ],
  "has_next": true,
  "has_prev": false,
  "page": 0,
  "per_page": 30
}

Message Tools

mattermost_post_message

Post a new message to a channel.

Returns:

{
  "id": "post-id",
  "channel_id": "channel-id",
  "message": "Hello, world!",
  "create_at": "2024-11-04T14:06:82.000Z"
}

mattermost_reply_to_thread

Reply to a specific message thread.

Returns:

{
  "id": "reply-id",
  "channel_id": "channel-id",
  "root_id": "parent-post-id",
  "message": "This is a reply",
  "create_at": "2024-11-04T14:06:82.000Z"
}

mattermost_add_reaction

Add an emoji reaction to a message.

Returns:

{
  "post_id": "post-id",
  "user_id": "user-id",
  "emoji_name": "thumbsup",
  "create_at": "2024-12-11T15:31:30.000Z"
}

mattermost_get_thread_replies

Retrieve all replies in a message thread.

Returns:

{
  "posts": [
    {
      "id": "reply-id",
      "user_id": "user-id",
      "message": "Reply message",
      "create_at": "2024-11-04T14:06:82.000Z",
      "root_id": "parent-post-id"
    }
  ],
  "root_post": {
    "id": "parent-post-id",
    "user_id": "user-id",
    "message": "Original message",
    "create_at": "2024-12-11T15:30:00.000Z"
  }
}

User Tools

mattermost_get_users

List workspace users with pagination.

Returns:

{
  "users": [
    {
      "id": "user-id",
      "username": "john.doe",
      "email": "john@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "nickname": "Johnny",
      "position": "Developer",
      "roles": "system_user",
      "is_bot": false
    }
  ],
  "total_count": 150,
  "page": 0,
  "per_page": 100
}

mattermost_get_user_profile

Get detailed profile information for a specific user.

Returns:

{
  "id": "user-id",
  "username": "john.doe",
  "email": "john@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "nickname": "Johnny",
  "position": "Developer",
  "roles": "system_user system_admin",
  "locale": "en",
  "timezone": "Asia/Dubai",
  "is_bot": false,
  "create_at": "2023-01-15T10:00:00.000Z",
  "update_at": "2024-12-01T14:30:00.000Z"
}

Monitoring Tools

mattermost_run_monitoring

Trigger the topic monitoring process immediately (outside of scheduled intervals).

Returns:

{
  "success": true,
  "message": "Monitoring completed successfully"
}

mattermost_get_monitoring_status

Get current monitoring system status.

Returns:

{
  "enabled": true,
  "running": true,
  "message": "Monitoring is active"
}

Installation

Prerequisites

• Python 3.14+ (or 3.11+ with minor adjustments)
• Mattermost Personal Access Token with appropriate permissions
• Anthropic API Key (optional, for semantic topic analysis)

Quick Start

# Clone the repository
git clone https://github.com/adeg/mattermost-mcp.git
cd mattermost-mcp

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e .

# Copy and configure environment
cp .env.example .env
# Edit .env with your configuration

# Run the server
python -m mattermost_mcp.main

Using uv (Recommended)

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv pip install -e .

# Run with uv
uv run python -m mattermost_mcp.main

Development Installation

# Install with development dependencies
pip install -e ".[dev]"

# Or using Make
make dev

Configuration

Configuration is managed through environment variables. Copy .env.example to .env and adjust the values:

cp .env.example .env

Required Settings

Server Settings

Topic Monitoring Settings

LLM Settings (Optional)

Example Configuration

# Required
MATTERMOST_URL=https://mattermost.company.com
MATTERMOST_TOKEN=your-personal-access-token
MATTERMOST_TEAM_ID=your-team-id

# Server
HTTP_PORT=8000
LOG_LEVEL=INFO
LOG_FORMAT=json

# Monitoring
MONITORING_ENABLED=true
MONITORING_SCHEDULE=*/5 * * * *
MONITORING_CHANNELS=general,engineering,support
MONITORING_TOPICS=urgent,outage,help needed

# LLM (optional but recommended for semantic matching)
ANTHROPIC_API_KEY=sk-ant-api03-xxx

Docker Deployment

Building the Image

# Using Make
make docker-build

# Or directly
docker build -f infra/docker/Dockerfile -t mattermost-mcp:latest .

Running the Container

# Using Make (reads from .env file)
make docker-run

# Or directly
docker run -d \
  --name mattermost-mcp \
  --env-file .env \
  -p 8000:8000 \
  -v mattermost-mcp-data:/data/mattermost-mcp \
  mattermost-mcp:latest

Docker Compose Example

version: '3.8'

services:
  mattermost-mcp:
    build:
      context: .
      dockerfile: infra/docker/Dockerfile
    container_name: mattermost-mcp
    restart: unless-stopped
    ports:
      - "8000:8000"
    environment:
      - MATTERMOST_URL=${MATTERMOST_URL}
      - MATTERMOST_TOKEN=${MATTERMOST_TOKEN}
      - MATTERMOST_TEAM_ID=${MATTERMOST_TEAM_ID}
      - MONITORING_ENABLED=${MONITORING_ENABLED:-false}
      - MONITORING_CHANNELS=${MONITORING_CHANNELS:-}
      - MONITORING_TOPICS=${MONITORING_TOPICS:-}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY:-}
    volumes:
      - mattermost-mcp-data:/data/mattermost-mcp
    healthcheck:
      test: ["CMD", "python", "-c", "import httpx; httpx.get('http://localhost:8000/health').raise_for_status()"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 5s

volumes:
  mattermost-mcp-data:

Dockerfile Overview

The Dockerfile uses a multi-stage build for optimal image size:

1. Builder Stage: Installs uv for fast dependency resolution and creates a virtual environment
2. Production Stage: Minimal Python runtime with only the application code and dependencies

Key security features:

• Runs as non-root user (mcp:mcp)
• No development dependencies in production image
• Health check endpoint validation

Nomad Deployment

The project includes a Nomad job specification at infra/nomad/mattermost-mcp.nomad.hcl.

Prerequisites

• HashiCorp Nomad cluster
• HashiCorp Vault for secrets management
• Traefik for ingress (optional)
• Container registry with the built image

Vault Secrets Setup

Store secrets in Vault at secret/data/mattermost-mcp:

vault kv put secret/mattermost-mcp \
  mattermost_url="https://mattermost.example.com" \
  mattermost_token="your-token" \
  team_id="your-team-id" \
  anthropic_api_key="your-anthropic-key" \  # pragma: allowlist secret
  monitoring_enabled="true" \
  monitoring_channels="general,engineering" \
  monitoring_topics="urgent,help"

Deploying the Job

# Plan the deployment
nomad job plan infra/nomad/mattermost-mcp.nomad.hcl

# Run the deployment
nomad job run infra/nomad/mattermost-mcp.nomad.hcl

# Check status
nomad job status mattermost-mcp

Job Configuration Highlights

Health Checks

The Nomad job configures two health checks:

• Liveness: GET /health every 30 seconds
• Readiness: GET /ready every 60 seconds (includes Mattermost connectivity check)

Traefik Integration

The job includes Traefik tags for automatic routing:

tags = [
  "traefik.enable=true",
  "traefik.http.routers.mattermost-mcp.rule=Host(`mcp.example.com`)",
  "traefik.http.routers.mattermost-mcp.tls=true"
]

Persistent Storage

The job mounts a host volume for monitoring state persistence:

volume "data" {
  type   = "host"
  source = "mattermost-mcp-data"
}

Configuring Topic Monitoring

The topic monitoring system automatically scans configured channels for messages related to specified topics and sends notifications when relevant content is found.

Enabling Monitoring

MONITORING_ENABLED=true
MONITORING_SCHEDULE=*/5 * * * *
MONITORING_CHANNELS=general,engineering,support
MONITORING_TOPICS=urgent,outage,incident,help needed

How It Works

1. Scheduled Execution: The monitor runs on the configured cron schedule (default: every 5 minutes)
2. Channel Scanning: Fetches recent messages from each configured channel
3. Deduplication: Tracks processed messages to avoid duplicate notifications
4. Topic Detection: Analyzes messages using LLM semantic matching or keyword fallback
5. Notification Delivery: Sends DM notifications with relevant message details

Topic Detection Methods

LLM Semantic Analysis (Recommended)

When ANTHROPIC_API_KEY is configured, the system uses Claude AI for intelligent topic matching:

• Understands context and synonyms (e.g., "ping pong" matches "table tennis")
• Handles natural language variations
• Reduces false positives from keyword-only matching

Keyword Fallback

Without an API key, the system falls back to case-insensitive keyword matching:

• Fast and deterministic
• No external API dependencies
• Best for exact term matching

State Persistence

The monitoring system maintains state in a JSON file (MONITORING_STATE_PATH) to:

• Track processed messages across restarts
• Prevent duplicate notifications
• Record last run timestamp

First Run Behavior

On first run, you can control how existing messages are handled:

Notification Format

Notifications are sent as direct messages with:

• Channel name and message count
• Up to 5 relevant messages with:
  • Author username
  • Timestamp
  • Message preview
  • Link to original post
  • Matching topics

Manual Triggering

Use the mattermost_run_monitoring MCP tool to trigger monitoring immediately:

# Via MCP client
result = await mcp_client.call_tool("mattermost_run_monitoring", {})

Monitoring Status

Check the current monitoring status:

# Via MCP client
status = await mcp_client.call_tool("mattermost_get_monitoring_status", {})
# Returns: {"enabled": true, "running": true, "message": "Monitoring is active"}

Development

Setup

# Install development dependencies
make dev

# This installs:
# - All runtime dependencies
# - pytest, pytest-asyncio, pytest-cov
# - ruff, mypy
# - Pre-commit hooks

Available Make Commands

Code Quality Tools

Ruff (Linting & Formatting)

# Check for issues
make lint

# Auto-fix and format
make format

Ruff configuration (in pyproject.toml):

• Line length: 120 characters
• Target Python: 3.14
• Comprehensive rule set (pycodestyle, pyflakes, isort, bugbear, etc.)

MyPy (Type Checking)

make type-check

The project uses strict type hints with Pydantic models for runtime validation.

Pre-commit Hooks

Pre-commit hooks run automatically on git commit:

• File checks (trailing whitespace, EOF, YAML/JSON validation)
• Secret detection (gitleaks, detect-secrets)
• Python linting and formatting (ruff)
• Type checking (mypy)
• Markdown linting

Manual run:

pre-commit run --all-files

Testing

# Run all tests with coverage
make test

# Or directly with pytest
pytest tests/ -v --cov=mattermost_mcp --cov-report=term-missing

Test fixtures are available in tests/conftest.py:

• mock_mattermost_client: Async-enabled mock client
• sample_channel: Sample channel data
• sample_post: Sample post data
• sample_user: Sample user data

Running Locally

# Start the server
make run

# Or directly
python -m mattermost_mcp.main

The server starts on port 8000 with:

• MCP Endpoint: http://localhost:8000/llm/mcp
• Health Check: http://localhost:8000/health
• Readiness Check: http://localhost:8000/ready
• Root Info: http://localhost:8000/

Project Structure

mattermost-mcp/
├── src/mattermost_mcp/           # Main application package
│   ├── __init__.py               # Package version
│   ├── main.py                   # FastAPI application entry point
│   ├── config.py                 # Pydantic settings management
│   ├── logging.py                # Structured logging configuration
│   │
│   ├── api/                      # REST API endpoints
│   │   └── health.py             # Health and readiness endpoints
│   │
│   ├── clients/                  # External service clients
│   │   └── mattermost.py         # Async Mattermost API wrapper
│   │
│   ├── models/                   # Data models
│   │   └── mattermost.py         # Pydantic models for API responses
│   │
│   ├── mcp/                      # MCP server implementation
│   │   ├── server.py             # FastMCP server instance
│   │   └── tools/                # MCP tool definitions
│   │       ├── channels.py       # Channel tools
│   │       ├── messages.py       # Message tools
│   │       ├── users.py          # User tools
│   │       └── monitoring.py     # Monitoring tools
│   │
│   └── monitoring/               # Topic monitoring system
│       ├── monitor.py            # Main orchestrator
│       ├── analyzer.py           # Message analysis (LLM + keyword)
│       ├── scheduler.py          # APScheduler wrapper
│       └── persistence.py        # State management
│
├── infra/                        # Infrastructure configuration
│   ├── docker/
│   │   ├── Dockerfile            # Multi-stage Docker build
│   │   └── .dockerignore
│   └── nomad/
│       └── mattermost-mcp.nomad.hcl  # Nomad job specification
│
├── tests/                        # Test suite
│   ├── conftest.py               # Pytest fixtures
│   └── test_mcp_tools.py         # Tool and model tests
│
├── pyproject.toml                # Project metadata and tool config
├── Makefile                      # Development automation
├── .env.example                  # Configuration template
├── .pre-commit-config.yaml       # Pre-commit hooks
└── .mise.toml                    # Tool version management

Module Responsibilities

Solution Architecture

System Overview

┌───────────────────────────────────────────────────────────────────┐
│                        Mattermost MCP Server                      │
├───────────────────────────────────────────────────────────────────┤
│                                                                   │
│  ┌──────────────┐    ┌──────────────┐    ┌────────────────────┐   │
│  │   FastAPI    │    │   FastMCP    │    │  Topic Monitoring  │   │
│  │   (HTTP)     │    │   (MCP)      │    │    (Scheduler)     │   │
│  └──────┬───────┘    └──────┬───────┘    └─────────┬──────────┘   │
│         │                   │                      │              │
│         │    ┌──────────────┴───────────────┐      │              │
│         │    │         MCP Tools            │      │              │
│         │    │  ┌──────────┬─────────────┐  │      │              │
│         │    │  │ Channels │  Messages   │  │      │              │
│         │    │  ├──────────┼─────────────┤  │      │              │
│         │    │  │   Users  │ Monitoring  │  │      │              │
│         │    │  └──────────┴─────────────┘  │      │              │
│         │    └──────────────┬───────────────┘      │              │
│         │                   │                      │              │
│         └───────────────────┼──────────────────────┘              │
│                             │                                     │
│                    ┌────────▼────────┐                            │
│                    │ MattermostClient│                            │
│                    │   (Async)       │                            │
│                    └────────┬────────┘                            │
│                             │                                     │
└─────────────────────────────┼─────────────────────────────────────┘
                              │
                    ┌─────────▼─────────┐
                    │  Mattermost API   │
                    │   (External)      │
                    └───────────────────┘

Request Flow: MCP Tool Call

1. LLM/Client sends MCP tool request
   │
   ▼
2. FastMCP receives request at /llm/mcp
   │
   ▼
3. Tool function invoked (e.g., mattermost_post_message)
   │
   ▼
4. MattermostClient method called (async)
   │
   ├─► Ensures login via await self.login()
   │
   └─► Wraps sync driver call with asyncio.to_thread()
       │
       ▼
5. mattermostautodriver makes HTTP request to Mattermost
   │
   ▼
6. Response converted to Pydantic model
   │
   ▼
7. Formatted response returned to LLM/Client

Monitoring Pipeline

                    ┌────────────────────┐
                    │  APScheduler Cron  │
                    │   (*/5 * * * *)    │
                    └─────────┬──────────┘
                              │ triggers
                              ▼
                    ┌────────────────────┐
                    │   TopicMonitor     │
                    │  _run_monitoring() │
                    └─────────┬──────────┘
                              │
           ┌──────────────────┼──────────────────┐
           ▼                  ▼                  ▼
    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
    │  Channel 1  │    │  Channel 2  │    │  Channel N  │
    │   Analysis  │    │   Analysis  │    │   Analysis  │
    └──────┬──────┘    └──────┬──────┘    └──────┬──────┘
           │                  │                  │
           └──────────────────┼──────────────────┘
                              │
                              ▼
                    ┌────────────────────┐
                    │  MessageAnalyzer   │
                    │  _analyze_posts_*  │
                    └─────────┬──────────┘
                              │
              ┌───────────────┴───────────────┐
              ▼                               ▼
    ┌──────────────────┐            ┌──────────────────┐
    │   LLM Analysis   │            │ Keyword Fallback │
    │  (Claude API)    │            │  (No API Key)    │
    └────────┬─────────┘            └────────┬─────────┘
             │                               │
             └───────────────┬───────────────┘
                             │
                             ▼
                   ┌────────────────────┐
                   │  StateManager      │
                   │  (Deduplication)   │
                   └─────────┬──────────┘
                             │
                             ▼
                   ┌────────────────────┐
                   │  Send Notification │
                   │  (DM to User)      │
                   └────────────────────┘

Error Handling Strategy

The system implements three tiers of error handling:

Async Design

All I/O operations use async/await to prevent blocking:

• FastAPI: Async request handlers
• FastMCP: Async tool functions
• MattermostClient: Uses asyncio.to_thread() to wrap sync driver
• Monitoring: Uses AsyncIOScheduler from APScheduler
• Anthropic: Uses async client for LLM calls

Component Interactions

┌─────────────────────────────────────────────────────────────────┐
│                       Configuration Layer                       │
│  ┌──────────┐  ┌──────────────────┐  ┌────────────┐             │
│  │ Settings │  │ MonitoringConfig │  │ LlmConfig  │             │
│  └────┬─────┘  └────────┬─────────┘  └─────┬──────┘             │
└───────┼─────────────────┼──────────────────┼────────────────────┘
        │                 │                  │
        ▼                 ▼                  ▼
┌─────────────────────────────────────────────────────────────────┐
│                        Application Layer                        │
│  ┌──────────────────────────────────────────────────────┐       │
│  │                    main.py                           │       │
│  │  - Lifespan management (startup/shutdown)            │       │
│  │  - FastAPI + FastMCP mounting                        │       │
│  │  - Health endpoints                                  │       │
│  └──────────────────────────────────────────────────────┘       │
└─────────────────────────────────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────────────────────────────────┐
│                        Service Layer                            │
│  ┌────────────────┐     ┌────────────────┐                      │
│  │ MCP Tools      │     │ TopicMonitor   │                      │
│  │ (channels,     │     │ (scheduler,    │                      │
│  │  messages,     │     │  analyzer,     │                      │
│  │  users,        │     │  persistence)  │                      │
│  │  monitoring)   │     │                │                      │
│  └───────┬────────┘     └───────┬────────┘                      │
└──────────┼──────────────────────┼───────────────────────────────┘
           │                      │
           ▼                      ▼
┌─────────────────────────────────────────────────────────────────┐
│                        Client Layer                             │
│  ┌────────────────────────┐  ┌────────────────────────────┐     │
│  │   MattermostClient     │  │   Anthropic Async Client   │     │
│  │   (mattermostautodriver│  │   (Claude API)             │     │
│  │    TypedDriver)        │  │                            │     │
│  └────────────────────────┘  └────────────────────────────┘     │
└─────────────────────────────────────────────────────────────────┘
           │                      │
           ▼                      ▼
    ┌──────────────┐      ┌──────────────┐
    │ Mattermost   │      │  Anthropic   │
    │ API v4       │      │  API         │
    └──────────────┘      └──────────────┘

License

MIT