Mattermost MCP Server¶

A Model Context Protocol (MCP) server that provides AI agents and automation tools with secure access to Mattermost channels, users, and content.

Features¶

MCP Protocol Support: Implements the Model Context Protocol for standardized AI agent communication
Authentication: Personal Access Token (PAT) authentication
Transport: Configurable transport layer (currently stdio JSON-RPC for local desktop clients like Claude Desktop)
Comprehensive Mattermost Integration: Read posts, channels, search, create content
Dual Mode Operation: Runs standalone or embedded in the AI plugin

Tools Available¶

The MCP server exposes the following tools to AI agents:

`read_post`¶

Read a specific post and its thread from Mattermost.

Parameters:

post_id (required): The ID of the post to read
include_thread (optional): Whether to include the entire thread (default: true)

`read_channel`¶

Read recent posts from a Mattermost channel.

Parameters:

channel_id (required): The ID of the channel to read from
limit (optional): Number of posts to retrieve (default: 20, max: 100)
since (optional): Only get posts since this timestamp (ISO 8601 format)

`search_posts`¶

Search for posts in Mattermost.

Parameters:

query (required): The search query
team_id (optional): Team ID to limit search scope
channel_id (optional): Channel ID to limit search to a specific channel
limit (optional): Number of results to return (default: 20, max: 100)

`create_post`¶

Create a new post in Mattermost.

Parameters:

channel_id (required): The ID of the channel to post in
message (required): The message content
root_id (optional): Root post ID for replies
props (optional): Post properties
attachments (optional): Array of file paths or URLs to attach to the post
- Note: File paths only work with Claude Code; Claude Desktop cannot access local files

`create_channel`¶

Create a new channel in Mattermost.

Parameters:

name (required): The channel name (URL-friendly)
display_name (required): The channel display name
type (required): Channel type - ‘O’ for public, ‘P’ for private
team_id (required): The team ID where the channel will be created
purpose (optional): Channel purpose
header (optional): Channel header

`get_channel_info`¶

Get information about a channel. If you have a channel ID, use that for fastest lookup. If the user provides a human-readable name, try channel_display_name first (what users see in the UI), then channel_name (URL name) as fallback.

Parameters:

channel_id: The exact channel ID (fastest, most reliable method)
channel_display_name + team_id: The human-readable display name users see (e.g. ‘General Discussion’)
channel_name + team_id: The URL-friendly channel name (e.g. ‘general-discussion’)

`get_team_info`¶

Get information about a team. If you have a team ID, use that for fastest lookup. If the user provides a human-readable name, try team_display_name first (what users see in the UI), then team_name (URL name) as fallback.

Parameters:

team_id: The exact team ID (fastest, most reliable method)
team_display_name: The human-readable display name users see (e.g. ‘Engineering Team’)
team_name: The URL-friendly team name (e.g. ‘engineering-team’)

`search_users`¶

Search for existing users by username, email, or name.

Parameters:

term (required): Search term (username, email, first name, or last name)
limit (optional): Maximum number of results to return (default: 20, max: 100)

`get_channel_members`¶

Get all members of a specific channel with their details.

Parameters:

channel_id (required): ID of the channel to get members for

`get_team_members`¶

Get all members of a specific team with their details.

Parameters:

team_id (required): ID of the team to get members for

Development Tools (Dev Mode Only)¶

The following tools are only available when the -dev flag is enabled:

`create_user`¶

Create a new user account for testing scenarios.

Parameters: username, email, password, first_name (optional), last_name (optional), nickname (optional), profile_image (optional): File path or URL to set as profile image (supports .jpeg, .jpg, .png, .gif)
- Note: File paths only work with Claude Code; Claude Desktop cannot access local files

`create_team`¶

Create a new team.

Parameters: name, display_name, type (O for open, I for invite only), description (optional), team_icon (optional): File path or URL to set as team icon (supports .jpeg, .jpg, .png, .gif)
- Note: File paths only work with Claude Code; Claude Desktop cannot access local files

`add_user_to_team`¶

Add a user to a team.

Parameters: user_id, team_id

`add_user_to_channel`¶

Add a user to a channel.

Parameters: user_id, channel_id

`create_post_as_user`¶

Create a post as a specific user using username/password login. Simply provide the username and password of created users.

Parameters:
- username (required), password (required)
- channel_id (required), message (required)
- root_id (optional), props (optional)
- attachments (optional): Array of file paths or URLs to attach to the post
- Note: File paths only work with Claude Code; Claude Desktop cannot access local files

Installation and Usage¶

Build¶

Build the server:

# Using the Makefile (recommended)
make mcp-server

# Or manually from the project root
go build -o bin/mattermost-mcp-server ./mcpserver/cmd/main.go

Set up authentication:
- Create a Personal Access Token in Mattermost (User Settings > Security > Personal Access Tokens)
- Note your Mattermost server URL

Configuration Options¶

Required:

--server-url: Mattermost server URL (or set MM_SERVER_URL env var)
--token: Personal Access Token (or set MM_ACCESS_TOKEN env var)

Optional:

--transport: Transport type (currently only ‘stdio’ is supported, default: ‘stdio’)
--logfile: Path to log file (logs to file in addition to stderr, JSON format)
--debug: Enable debug logging (recommended for troubleshooting)
--dev: Enable development mode with additional tools for setting up test data
--version: Show version information

Notes:

Token validation occurs at startup for fast failure detection
Logging output goes to stderr to avoid interfering with JSON-RPC communication on stdout
File logging (when --logfile is used) outputs structured JSON logs in addition to stderr
Debug logging includes tool call tracing and detailed operation logs

Integration with AI Clients¶

Claude Code Integration¶

claude mcp add mattermost -e MM_SERVER_URL=https://mattermost-url MM_ACCESS_TOKEN=<token> -- /path/to/mattermost-plugin-ai/bin/mattermost-mcp-server --dev --debug

Claude Desktop Integration¶

To use with Claude Desktop, add the server to your MCP configuration:

macOS/Linux: ~/.config/claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mattermost": {
      "command": "/path/to/mattermost-plugin-ai/bin/mattermost-mcp-server",
      "args": ["--debug"],
      "env": {
        "MM_SERVER_URL": "https://your-mattermost.com",
        "MM_ACCESS_TOKEN": "your-pat-token"
      }
    }
  }
}

Development Mode¶

Development mode (--dev flag) enables additional tools for setting up realistic test data and user scenarios. This is particularly useful for Mattermost developers who need to bootstrap development environments or create sophisticated test scenarios.

Enable development mode:

./bin/mattermost-mcp-server --dev --server-url https://your-mattermost.com --token your-admin-pat-token

Security Note: Development mode should only be used in development environments with admin-level access tokens, never in production.

Mattermost MCP Server¶

Features¶

Tools Available¶

read_post¶

read_channel¶

search_posts¶

create_post¶

create_channel¶

get_channel_info¶

get_team_info¶

search_users¶

get_channel_members¶

get_team_members¶

Development Tools (Dev Mode Only)¶

create_user¶

create_team¶

add_user_to_team¶

add_user_to_channel¶

create_post_as_user¶

Installation and Usage¶

Build¶

Configuration Options¶

Integration with AI Clients¶

Claude Code Integration¶

Claude Desktop Integration¶

Development Mode¶

`read_post`¶

`read_channel`¶

`search_posts`¶

`create_post`¶

`create_channel`¶

`get_channel_info`¶

`get_team_info`¶

`search_users`¶

`get_channel_members`¶

`get_team_members`¶

`create_user`¶

`create_team`¶

`add_user_to_team`¶

`add_user_to_channel`¶

`create_post_as_user`¶