Mattermost MCP Server

Mattermost MCP Server

A Model Context Protocol (MCP) server for interacting with Mattermost workspaces. This server provides tools for managing channels, messages, threads, reactions, and user profiles through Mattermost's REST API.

Built on Cloudflare Workers using the Agents SDK.

Important: This is an MCP server without OAuth authentication, designed for trusted environments where the server runs with pre-configured API credentials.

Features

Tools (9 Total)

Read Operations (6 tools):

• list_mattermost_channels - List all channels in the team
• get_mattermost_channel_history - Get message history from a channel
• get_mattermost_thread_replies - Get all replies in a thread
• get_mattermost_users - List users in the workspace
• get_mattermost_user_profile - Get detailed profile for a specific user

Write Operations (3 tools):

• post_mattermost_message - Post a new message to a channel
• reply_to_mattermost_thread - Reply to an existing thread
• add_mattermost_reaction - Add emoji reactions to posts
• create_mattermost_direct_channel - Create a direct message channel with a user

Prompts (2 Total)

• mattermost_guide - Comprehensive guide for using Mattermost effectively
• message_template - Helpful templates for crafting effective Mattermost messages

Resources (2 Total)

• mattermost://channels - List of all channels in the team
• mattermost://users - List of all users in the workspace

Architecture

This MCP server is built using:

• Cloudflare Workers: Serverless compute
• Agents SDK: Framework for building AI agents and MCP Servers
• Durable Objects: For persistent MCP session state
• Mattermost REST API v4: For workspace integration

Prerequisites

• Node.js 18+
• A Mattermost instance (self-hosted or cloud)
• Personal Access Token from Mattermost (Profile → Security → Personal Access Tokens)
• Team ID from your Mattermost workspace

Quick Start

Local Development

1. Clone the repository:

git clone https://github.com/vnikhilbuddhavarapu/mattermost-mcp.git
cd mattermost-mcp

2. Install dependencies:

npm install

3. Configure environment variables:

cp .dev.vars.example .dev.vars

Edit .dev.vars with your Mattermost credentials:

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

Finding your Team ID:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://mattermost.your-domain.com/api/v4/teams | jq '.[].id'

4. Run locally:

npm run dev

Deploy to Cloudflare Workers

1. Click the deploy button above or run:

npm run deploy

2. Set your secrets:

npx wrangler secret put MATTERMOST_URL
npx wrangler secret put MATTERMOST_TOKEN
npx wrangler secret put MATTERMOST_TEAM_ID

Configuration

Environment Variables

Usage with MCP Clients

Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "mattermost": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mattermost-mcp.your-account.workers.dev/mcp"],
      "env": {
        "MATTERMOST_URL": "https://mattermost.your-domain.com",
        "MATTERMOST_TOKEN": "your-token-here",
        "MATTERMOST_TEAM_ID": "your-team-id"
      }
    }
  }
}

Other MCP Clients

Connect to the MCP endpoint:

https://mattermost-mcp.your-account.workers.dev/mcp

Project Structure

src/
├── index.ts                 # Main MCP server setup and Durable Object
├── mattermost-client.ts     # REST API client for Mattermost
├── shared/
│   └── utils.ts            # Logging utilities and request ID generation
├── tools/                   # MCP tool implementations
│   ├── list-channels.ts
│   ├── get-channel-history.ts
│   ├── post-message.ts
│   ├── reply-to-thread.ts
│   ├── get-thread-replies.ts
│   ├── add-reaction.ts
│   ├── get-users.ts
│   ├── get-user-profile.ts
│   ├── create-direct-channel.ts
│   └── index.ts            # Tool exports
├── prompts/                # MCP prompt templates
│   ├── mattermost-guide.ts
│   ├── message-template.ts
│   └── index.ts            # Prompt exports
└── resources/              # MCP resources
    ├── channe