# Mcp Server Mattermost

> MCP server for Mattermost — let Claude, Cursor, and other AI assistants work with channels, messages, and files

- **Type:** MCP server
- **Install:** `agentstack add mcp-cloud-ru-tech-mcp-server-mattermost`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [cloud-ru-tech](https://agentstack.voostack.com/s/cloud-ru-tech)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [cloud-ru-tech](https://github.com/cloud-ru-tech)
- **Source:** https://github.com/cloud-ru-tech/mcp-server-mattermost
- **Website:** https://mcp-server-mattermost.readthedocs.io

## Install

```sh
agentstack add mcp-cloud-ru-tech-mcp-server-mattermost
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# mcp-server-mattermost

Let AI assistants read, search, and post in your Mattermost workspace

38 tools · Channels · Messages · Reactions · Threads · Files · Users

[](https://modelcontextprotocol.io/)
[](https://pypi.org/project/mcp-server-mattermost/)
[](https://hub.docker.com/r/legard/mcp-server-mattermost)
[](https://github.com/cloud-ru-tech/mcp-server-mattermost/actions)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://mcp-server-mattermost.readthedocs.io/)

## Features

**Channels** — list, create, join, manage channels and DMs
**Messages** — send, search, edit, delete with rich attachments
**Reactions & Threads** — emoji reactions, pins, full thread history
**Users & Teams** — lookup, search, status
**Files** — upload, metadata, download links
**Bookmarks** — save links and files in channels (Entry+ edition)

## Example Queries

Once configured, you can ask your AI assistant:

- "List all channels and find where the deployment discussion is happening"
- "What did I miss in #engineering since yesterday morning?"
- "Show me my unread channels and summarize the threads I was mentioned in"
- "Send a build status alert to #engineering with a red attachment"
- "Search for messages about the outage last week and summarize"
- "Summarize this thread and post the key decisions"
- "Find who worked on the authentication bug last week"
- "Upload the report.pdf to #general and share the link"

## Available Tools

Channels (11 tools)

| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `list_public_channels` | List public channels in a team | `team_id` ✓ |
| `list_my_channels` | List your channels with unread counts | `team_id` ✓, `only_unread` |
| `get_channel` | Get channel details by ID | `channel_id` ✓ |
| `get_channel_by_name` | Get channel by name | `team_id`, `channel_name` ✓ |
| `create_channel` | Create a new channel | `team_id`, `name`, `display_name` ✓ |
| `join_channel` | Join a public channel | `channel_id` ✓ |
| `leave_channel` | Leave a channel | `channel_id` ✓ |
| `mark_channel_viewed` | Mark a channel as viewed (reset unread counters) | `channel_id` ✓ |
| `get_channel_members` | List channel members | `channel_id` ✓ |
| `add_user_to_channel` | Add user to channel | `channel_id`, `user_id` ✓ |
| `create_direct_channel` | Create DM channel | `user_id_1`, `user_id_2` ✓ |

Messages (5 tools)

| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `post_message` | Send a message to a channel | `channel_id`, `message` ✓, `attachments` |
| `get_channel_messages` | Get messages: recent, unread window, or `since` timestamp | `channel_id` ✓, `unread_only`, `since` |
| `search_messages` | Search messages by term | `team_id`, `terms` ✓ |
| `update_message` | Edit a message | `post_id`, `message` ✓, `attachments` |
| `delete_message` | Delete a message | `post_id` ✓ |

Reactions & Threads (6 tools)

| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `add_reaction` | Add emoji reaction | `post_id`, `emoji_name` ✓ |
| `remove_reaction` | Remove emoji reaction | `post_id`, `emoji_name` ✓ |
| `get_reactions` | Get all reactions on a post | `post_id` ✓ |
| `pin_message` | Pin a message | `post_id` ✓ |
| `unpin_message` | Unpin a message | `post_id` ✓ |
| `get_thread` | Get thread messages | `post_id` ✓ |

Users (5 tools)

| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `get_me` | Get current user info | — |
| `get_user` | Get user by ID | `user_id` ✓ |
| `get_user_by_username` | Get user by username | `username` ✓ |
| `search_users` | Search users | `term` ✓ |
| `get_user_status` | Get online status | `user_id` ✓ |

Teams (3 tools)

| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `list_teams` | List your teams | — |
| `get_team` | Get team details | `team_id` ✓ |
| `get_team_members` | List team members | `team_id` ✓ |

Files (3 tools)

| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `upload_file` | Upload a file | `channel_id`, `file_path` ✓ |
| `get_file_info` | Get file metadata | `file_id` ✓ |
| `get_file_link` | Get download link | `file_id` ✓ |

Bookmarks (5 tools) — Requires Entry+ edition

> **Note:** Requires Entry, Professional, Enterprise, or Enterprise Advanced edition
> (not available in Team Edition). Minimum version: v10.1.

| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `list_bookmarks` | List channel bookmarks | `channel_id` ✓ |
| `create_bookmark` | Create link or file bookmark | `channel_id`, `display_name`, `bookmark_type` ✓ |
| `update_bookmark` | Update bookmark properties | `channel_id`, `bookmark_id` ✓ |
| `delete_bookmark` | Delete a bookmark | `channel_id`, `bookmark_id` ✓ |
| `update_bookmark_sort_order` | Reorder bookmark | `channel_id`, `bookmark_id`, `new_sort_order` ✓ |

## Quick Start

1. Get a [Mattermost bot token](https://developers.mattermost.com/integrate/admin-guide/admin-bot-accounts/)
2. Add to your MCP client config:

```json
{
  "mcpServers": {
    "mattermost": {
      "command": "uvx",
      "args": ["mcp-server-mattermost"],
      "env": {
        "MATTERMOST_URL": "https://your-server.com",
        "MATTERMOST_TOKEN": "your-token"
      }
    }
  }
}
```

3. Restart your client

> **[Full setup guide](https://mcp-server-mattermost.readthedocs.io/quickstart/)** — Claude Desktop, Cursor, Claude Code, Opencode, Docker, pip

## Configuration

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `MATTERMOST_URL` | Yes | — | Mattermost server URL |
| `MATTERMOST_AUTH_MODE` | No | `static_token` | Auth mode: `static_token`, `client_token`, or `oauth_proxy` |
| `MATTERMOST_TOKEN` | Conditional | — | Bot or personal token. Required for `static_token`. |
| `MATTERMOST_TIMEOUT` | No | 30 | Request timeout in seconds |
| `MATTERMOST_MAX_RETRIES` | No | 3 | Max retry attempts |
| `MATTERMOST_VERIFY_SSL` | No | true | Verify SSL certificates |
| `MATTERMOST_LOG_LEVEL` | No | INFO | Logging level |
| `MATTERMOST_LOG_FORMAT` | No | json | Log output format: `json` or `text` |
| `MATTERMOST_API_VERSION` | No | v4 | Mattermost API version |

For `client_token` and `oauth_proxy` modes — including Mattermost OAuth App
registration, all `MATTERMOST_OAUTH_*` settings, and MCP client connection — see
[Authentication](docs/authentication.md).

## Docker

### Stdio mode (default)

```bash
docker run -i --rm \
  -e MATTERMOST_URL=https://your-mattermost.com \
  -e MATTERMOST_TOKEN=your-token \
  legard/mcp-server-mattermost
```

Claude Desktop config

```json
{
  "mcpServers": {
    "mattermost": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MATTERMOST_URL=https://your-mattermost.com",
        "-e", "MATTERMOST_TOKEN=your-token",
        "legard/mcp-server-mattermost"
      ]
    }
  }
}
```

### HTTP mode (production)

```bash
docker run -d -p 8000:8000 \
  -e MCP_TRANSPORT=http \
  -e MCP_HOST=0.0.0.0 \
  -e MATTERMOST_URL=https://your-mattermost.com \
  -e MATTERMOST_TOKEN=your-token \
  legard/mcp-server-mattermost
```

Health check: `curl http://localhost:8000/health`

### HTTP mode with Mattermost OAuth proxy

Register a Mattermost OAuth 2.0 Application first:

| Mattermost field | Production value |
|------------------|------------------|
| Is Trusted | Yes |
| Is Public Client | No |
| Callback URLs | `https://mcp.example.com/oauth/callback/mm` |

Then run the MCP server:

```bash
docker run -d -p 8000:8000 \
  -e MCP_TRANSPORT=http \
  -e MCP_HOST=0.0.0.0 \
  -e MATTERMOST_AUTH_MODE=oauth_proxy \
  -e MATTERMOST_URL=https://mattermost.internal \
  -e MATTERMOST_OAUTH_MATTERMOST_PUBLIC_URL=https://mattermost.example.com \
  -e MATTERMOST_OAUTH_MCP_PUBLIC_URL=https://mcp.example.com \
  -e MATTERMOST_OAUTH_CLIENT_ID=your-mattermost-oauth-app-id \
  -e MATTERMOST_OAUTH_CLIENT_TYPE=confidential \
  -e MATTERMOST_OAUTH_CLIENT_SECRET=your-mattermost-oauth-app-secret \
  legard/mcp-server-mattermost
```

If your Mattermost login uses Keycloak SSO, users authenticate through Keycloak inside
the Mattermost OAuth login flow. The MCP server does not need a Keycloak client.

Connect Claude Code with Dynamic Client Registration:

```bash
claude mcp add --transport http mattermost https://mcp.example.com/mcp
```

Do not pass `--client-id` for this server; the MCP client registers with the MCP server,
and the MCP server uses the fixed Mattermost OAuth App upstream.

### Environment Variables (Docker)

| Variable | Default | Description |
|----------|---------|-------------|
| `MCP_TRANSPORT` | `stdio` | Transport: `stdio` or `http` |
| `MCP_HOST` | `127.0.0.1` | HTTP bind host (use `0.0.0.0` in Docker) |
| `MCP_PORT` | `8000` | HTTP port |

## Documentation

📖 **[mcp-server-mattermost.readthedocs.io](https://mcp-server-mattermost.readthedocs.io/)**

- [Quick Start](https://mcp-server-mattermost.readthedocs.io/quickstart/) — Installation and setup
- [Configuration](https://mcp-server-mattermost.readthedocs.io/configuration/) — Environment variables
- [Tools Reference](https://mcp-server-mattermost.readthedocs.io/tools/) — Detailed API documentation
- [llms.txt](https://github.com/cloud-ru-tech/mcp-server-mattermost/blob/main/llms.txt) — AI-readable documentation index

## Development

```bash
# Clone and install
git clone https://github.com/cloud-ru-tech/mcp-server-mattermost
cd mcp-server-mattermost
uv sync --dev

# Run unit tests
uv run pytest

# Run integration tests (requires Docker or external Mattermost)
uv run pytest tests/integration -v

# Type checking
uv run mypy src/

# Linting
uv run ruff check src/ tests/

# Run locally
MATTERMOST_URL=https://... MATTERMOST_TOKEN=... uv run mcp-server-mattermost
```

### Integration Tests

Integration tests run against a real Mattermost server via Docker (Testcontainers) or external server.

```bash
# With Docker (Testcontainers) — automatic setup
uv run pytest tests/integration -v

# Against external Mattermost server
export MATTERMOST_URL=https://your-server.com
export MATTERMOST_TOKEN=your-bot-token
uv run pytest tests/integration -v

# Run specific test module
uv run pytest tests/integration/test_channels.py -v
```

Integration tests are excluded from the default `pytest` run. Unit tests run with:

```bash
uv run pytest  # Unit tests only
```

## Debugging

Use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) to debug:

```bash
npx @modelcontextprotocol/inspector uvx mcp-server-mattermost
```

## Contributing

Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

MIT — see [LICENSE](LICENSE) for details.

---

Built with [FastMCP](https://gofastmcp.com/) · [Mattermost API v4](https://api.mattermost.com/)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [cloud-ru-tech](https://github.com/cloud-ru-tech)
- **Source:** [cloud-ru-tech/mcp-server-mattermost](https://github.com/cloud-ru-tech/mcp-server-mattermost)
- **License:** MIT
- **Homepage:** https://mcp-server-mattermost.readthedocs.io

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-cloud-ru-tech-mcp-server-mattermost
- Seller: https://agentstack.voostack.com/s/cloud-ru-tech
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.