ki_mattermost

Typed Python 3.14 client and CLI for self-hosted Mattermost (API v4). Built with uv and linted with Ruff.

Install

pip install ki_mattermost
# or
uv add ki_mattermost

Features

• List teams and channels
• Read channel messages and threads
• Create new threads (root posts)
• Comment (reply) in threads
• Like / unlike posts via emoji reactions (thumbsup by default)

Configuration

Set environment variables (or a local .env):

export MM_URL=https://mattermost.example.com
export MM_TOKEN=your-personal-access-token
# optional
export MM_TEAM_ID=
export MM_VERIFY_SSL=true
export MM_TIMEOUT=30

Create a Personal Access Token in Mattermost: Profile → Security → Personal Access Tokens (or use a bot account token).

CLI

After install, the ki-mattermost console script is available:

ki-mattermost whoami
ki-mattermost teams
ki-mattermost channels
ki-mattermost channels --team-id <TEAM_ID>

ki-mattermost posts <CHANNEL_ID> --flat
ki-mattermost thread <POST_ID> --flat

ki-mattermost create-thread <CHANNEL_ID> "Hello from API"
ki-mattermost comment <POST_ID> "Replying in thread"
ki-mattermost like <POST_ID>
ki-mattermost like <POST_ID> --emoji heart
ki-mattermost unlike <POST_ID>
ki-mattermost reactions <POST_ID>

Library usage

from ki_mattermost import MattermostClient, get_settings

with MattermostClient(get_settings()) as mm:
    channels = mm.list_channels()
    posts = mm.list_posts(channels[0].id)
    root = mm.create_thread(channels[0].id, "New thread")
    mm.comment(root.id, "First reply")
    mm.like(root.id)

Environment

Development

uv sync
cp .env.example .env
uv run ruff check .
uv run ruff format .
uv run ki-mattermost --help

Build & publish to PyPI

uv build
uv publish
# or with an explicit token:
# uv publish --token $UV_PUBLISH_TOKEN

Create an API token at https://pypi.org/manage/account/token/.