Mattermost MCP server for AI agents

This Mattermost MCP server enables Claude to interact with your Mattermost instance through the Model Context Protocol. It provides tools for managing posts, channels, users, and reactions, with optional Neo4j action tracking for advanced analytics and recommendations.

Installation

Quick Start with Docker

The fastest way to get started is using Docker with the provided configuration:

Clone the repository:

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

Create environment file:

cp env.example .env
# Edit .env with your configuration

Start the services:

docker-compose up -d

This will start both the MCP server and a Neo4j instance for action tracking.

Docker Deployment

Building the Docker Image

docker build -t mcp-mattermost .

Running with Docker

docker run -d \
  --name mcp-mattermost \
  -e MATTERMOST_URL="https://your-mattermost-instance.com" \
  -e MATTERMOST_TOKEN="your-personal-access-token" \
  -e NEO4J_URI="bolt://neo4j:7687" \
  -e NEO4J_USERNAME="neo4j" \
  -e NEO4J_PASSWORD="your_password" \
  mcp-mattermost

Environment Variables

Variable	Required	Description
`MATTERMOST_URL`	Yes	Your Mattermost instance URL
`MATTERMOST_TOKEN`	Yes	Personal access token for Mattermost
`NEO4J_URI`	No	Neo4j connection URI (for action tracking)
`NEO4J_USERNAME`	No	Neo4j username
`NEO4J_PASSWORD`	No	Neo4j password
`CURSOR_USER_ID`	No	User ID for Cursor integration
`CURSOR_USER_NAME`	No	User name for Cursor integration
`CURSOR_USER_EMAIL`	No	User email for Cursor integration
`CURSOR_USER_TEAM`	No	Team name for Cursor integration

Local Installation

Install dependencies:

npm install

Configure environment variables:

# Required: Mattermost configuration
export MATTERMOST_URL="https://your-mattermost-instance.com"
export MATTERMOST_TOKEN="your-personal-access-token"

# Optional: Neo4j Action Tracking
export NEO4J_URI="bolt://localhost:7687"
export NEO4J_USERNAME="neo4j"
export NEO4J_PASSWORD="your_password"

# Optional: Cursor Integration (for user identity)
export CURSOR_USER_ID="your_user_id"
export CURSOR_USER_NAME="Your Name"
export CURSOR_USER_EMAIL="[email protected]"
export CURSOR_USER_TEAM="Your Team"

Build and start the server:

npm run build
npm start

Neo4j Setup for Action Tracking (Optional)

If you want to enable advanced action tracking and analytics:

Using Docker (Recommended)

The docker-compose.yml file includes a Neo4j service that's automatically configured:

docker-compose up neo4j -d

Neo4j will be available at:

Browser interface: http://localhost:7474
Bolt connection: bolt://localhost:7687
Default credentials: neo4j/password (change via NEO4J_PASSWORD env var)

Usage

Available Tools

Post Management

mattermost_search_posts

Search posts with advanced modifiers support.

Parameters:

terms (string): Search term with optional modifiers
page (number, optional): Page number for pagination
perPage (number, optional): Number of posts per page

Search Modifiers:

from:username - Find posts from specific users
in:channel - Find posts in specific channels
before:YYYY-MM-DD - Find posts before a date
after:YYYY-MM-DD - Find posts after a date
on:YYYY-MM-DD - Find posts on a specific date
-term - Exclude posts containing the term
"exact phrase" - Search for exact phrases
term* - Wildcard search
#hashtag - Search for hashtags

Example:

{
  "terms": "meeting in:town-square from:john after:2023-01-01",
  "page": 0,
  "perPage": 50
}

mattermost_create_post

Create a new post in a channel.

Parameters:

channelId (string): Target channel ID
message (string): Message content
rootId (string, optional): Reply to this post ID

mattermost_get_posts

Get posts by their IDs.

Parameters:

postId (string): Comma-separated list of post IDs

mattermost_get_posts_unread

Get unread posts in a channel for the current user.

Parameters:

channelId (string): Channel ID

mattermost_get_posts_thread

Get all posts in a thread.

Parameters:

rootId (string): Thread parent post ID
perPage (number, optional): Number of posts per page
fromPost (string, optional): Start from this post ID

mattermost_pin_post / mattermost_unpin_post

Pin or unpin a post to/from a channel.

Parameters:

postId (string): Post ID to pin/unpin

mattermost_get_pinned_posts

Get all pinned posts in a channel.

Parameters:

channelId (string): Channel ID

Channel Management

mattermost_search_channels

Search channels by term.

Parameters:

term (string): Search term
page (number, optional): Page number
perPage (number, optional): Number of channels per page

mattermost_get_channels

Get channels by ID or name.

Parameters:

channelId (string, optional): Comma-separated channel IDs
name (string, optional): Comma-separated channel names

mattermost_get_my_channels

Get channels that the current user is a member of.

Parameters: None

User Management

mattermost_get_users

Get users by username or user ID.

Parameters:

username (string, optional): Comma-separated usernames
userId (string, optional): Comma-separated user IDs

mattermost_search_users

Search users by term.

Parameters:

term (string): Search term

Reaction Management

mattermost_add_reaction

Add emoji reactions to a post.

Parameters:

postId (string): Target post ID
emojiName (string): Comma-separated emoji names

mattermost_remove_reaction

Remove emoji reactions from a post.

Parameters:

postId (string): Target post ID
emojiName (string): Comma-separated emoji names

mattermost_get_reactions

Get all reactions for a post.

Parameters:

postId (string): Post ID

Neo4j Action Tracking Tools

mattermost_get_similar_actions

Find actions similar to the current one based on MCP type, action type, and parameters.

Parameters:

mcpType (string): Type of MCP (Mattermost, DynamoDB, Jira, etc.)
actionType (string): Type of action being performed
parameters (object): Parameters of the action
limit (number, optional): Maximum number of similar actions to return (default: 5)

Example:

{
  "mcpType": "Mattermost",
  "actionType": "post_creation",
  "parameters": {
    "channelId": "channel123"
  },
  "limit": 10
}

mattermost_get_user_history

Get a user's action history.

Parameters:

userId (string): ID of the user
limit (number, optional): Maximum number of actions to return (default: 20)

mattermost_suggest_next_action

Suggest the next action based on historical patterns.

Parameters:

userId (string): ID of the user
mcpType (string): Type of MCP
currentActionType (string): Type of the current action
currentParameters (object): Parameters of the current action

mattermost_find_user_by_email

Find a user by email in the action tracking system.

Parameters:

email (string): Email of the user to find
env (string): Environment ('uat' or 'prod')

Integration with Cursor

To use this server with Cursor, add this to your cursor_desktop_config.json:

{
  "mcpServers": {
    "mattermost": {
      "command": "node",
      "args": ["/path/to/mcp-mattermost/build/index.js"],
      "env": {
        "MATTERMOST_URL": "https://your-mattermost-instance.com",
        "MATTERMOST_TOKEN": "your-personal-access-token",
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "your_password",
        "CURSOR_USER_ID": "your_user_id",
        "CURSOR_USER_NAME": "Your Name",
        "CURSOR_USER_EMAIL": "[email protected]",
        "CURSOR_USER_TEAM": "Your Team"
      },
      "includeAuth": true,
      "authHeaders": {
        "cursor-auth": "${BASE64_ENCODED_USER_INFO}"
      }
    }
  }
}

Using with Docker

If you're running the server in Docker, use this configuration:

{
  "mcpServers": {
    "mattermost": {
      "command": "docker",
      "args": ["exec", "mcp-mattermost", "node", "build/index.js"],
      "env": {
        "CURSOR_USER_ID": "your_user_id",
        "CURSOR_USER_NAME": "Your Name",
        "CURSOR_USER_EMAIL": "[email protected]",
        "CURSOR_USER_TEAM": "Your Team"
      },
      "includeAuth": true
    }
  }
}

Troubleshooting

Connection Issues

The server uses lazy initialization, so it will start successfully even if Mattermost is unavailable. Connection errors will only occur when tools are invoked.

Neo4j Connection

If Neo4j action tracking fails to connect:

Verify Neo4j is running (check docker-compose logs neo4j)
Check environment variables are correctly set
Ensure Neo4j credentials are correct
The server will continue to work without action tracking

Docker Issues

Common Docker problems:

Build failures: Ensure all dependencies are correctly specified in package.json
Permission issues: The container runs as non-root user mcp (uid 1001)
Environment variables: Use docker-compose or set env vars correctly

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "mattermost" '{"command":"node","args":["/path/to/mcp-mattermost/build/index.js"],"env":{"MATTERMOST_URL":"https://your-mattermost-instance.com","MATTERMOST_TOKEN":"your-personal-access-token","NEO4J_URI":"bolt://localhost:7687","NEO4J_USERNAME":"neo4j","NEO4J_PASSWORD":"your_password","CURSOR_USER_ID":"your_user_id","CURSOR_USER_NAME":"Your Name","CURSOR_USER_EMAIL":"[email protected]","CURSOR_USER_TEAM":"Your Team"},"includeAuth":true,"authHeaders":{"cursor-auth":"${BASE64_ENCODED_USER_INFO}"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "mattermost": {
            "command": "node",
            "args": [
                "/path/to/mcp-mattermost/build/index.js"
            ],
            "env": {
                "MATTERMOST_URL": "https://your-mattermost-instance.com",
                "MATTERMOST_TOKEN": "your-personal-access-token",
                "NEO4J_URI": "bolt://localhost:7687",
                "NEO4J_USERNAME": "neo4j",
                "NEO4J_PASSWORD": "your_password",
                "CURSOR_USER_ID": "your_user_id",
                "CURSOR_USER_NAME": "Your Name",
                "CURSOR_USER_EMAIL": "[email protected]",
                "CURSOR_USER_TEAM": "Your Team"
            },
            "includeAuth": true,
            "authHeaders": {
                "cursor-auth": "${BASE64_ENCODED_USER_INFO}"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "mattermost": {
            "command": "node",
            "args": [
                "/path/to/mcp-mattermost/build/index.js"
            ],
            "env": {
                "MATTERMOST_URL": "https://your-mattermost-instance.com",
                "MATTERMOST_TOKEN": "your-personal-access-token",
                "NEO4J_URI": "bolt://localhost:7687",
                "NEO4J_USERNAME": "neo4j",
                "NEO4J_PASSWORD": "your_password",
                "CURSOR_USER_ID": "your_user_id",
                "CURSOR_USER_NAME": "Your Name",
                "CURSOR_USER_EMAIL": "[email protected]",
                "CURSOR_USER_TEAM": "Your Team"
            },
            "includeAuth": true,
            "authHeaders": {
                "cursor-auth": "${BASE64_ENCODED_USER_INFO}"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect