Configuration¶
mm-mcp reads its configuration from its environment, which an MCP client sets in
the server's env block. No setting is a command-line flag that carries a secret
(ADR-019). A value a client
leaves as an unexpanded placeholder, such as ${user_config.mm_token} for a
setting left empty, counts as unset.
Environment variables¶
MM_URL- Required. The address you open Mattermost at, such as
https://chat.example.com. Anhttporhttpsaddress, without a query; the API's own/api/v4at its end is dropped. A plainhttpaddress beyond this machine is warned about at start, since the token would cross the network unencrypted. A redirect to another address is refused and named, so set the address Mattermost is served at. MM_TOKEN- The credential mm-mcp acts with: a personal access token, a bot token, or
a session token. The server acts as whoever owns it. Leave it unset once
mm-mcp loginkeeps a token or a login forMM_URL, which is then used; a token set here goes first. MM_MCP_ALLOW_WRITES-
Optional,
falseby default.trueoffers the tools that post and change things in Mattermost. Your MCP client's own approval of each call decides whether a change goes ahead: its prompt, its permission rules or its auto mode (ADR-033). mm-mcp checks what each call states before it acts: how many people a post or an edit reaches and a post notifies, the text an edit replaces and the reactions and replies that answer it, how much a deletion takes away, and where it goes, by address (Tools). A change that is yours alone or gone in seconds, such as following a thread, saving a post, proposing one as your draft, or showing that you are typing, is a write all the same (ADR-021). Acceptstrue,false,1,0,yes,no,onandoff.A client that approves on its own writes as you
A client that approves tools by itself, such as Claude Code in auto mode, after "don't ask again", or under a rule that allows the tool, posts under your name with nobody seeing it first. In Claude Code, an
askrule orMM_MCP_FORCE_HUMAN_IN_THE_LOOP_IN_CLAUDE_CODEkeeps a person on every post. MM_MCP_ELICITATION_OPT_IN- Optional,
falseby default.truehas mm-mcp ask you as well before each change others see, onceMM_MCP_ALLOW_WRITESis true: a question your MCP client shows (an MCP elicitation), with what will be sent, where and under whose name. It is a convenience where your client shows the question, not a safeguard: some clients answer it without showing it, such as Claude Code in the Claude desktop app's Code tab, which declines it unseen, and mm-mcp cannot tell their answer from yours. While it is on, a client that cannot show a question at all is refused every such change. A change that is yours alone or gone in seconds never asks, and neither does your press in a view, which is your own action:MM_MCP_POST_FROM_VIEWS=falsekeeps Post out of the views. MM_MCP_ASK_BEFORE_WRITES- Sets nothing. A server started with it set stops and says to remove it;
MM_MCP_ELICITATION_OPT_INdecides whether mm-mcp asks. MM_MCP_FORCE_HUMAN_IN_THE_LOOP_IN_CLAUDE_CODE-
Optional,
falseby default, and not withMM_MCP_ELICITATION_OPT_IN=true: with both, you would be asked twice for one write, so mm-mcp does not start.truemarks each tool that changes what others see so that Claude Code asks a person on every call, in every permission mode, auto mode included, and no allow rule or "don't ask again" skips it (Claude Code). Use it to keep a person on every post, for example with a model you trust less. An agent that should post on its own cannot while it is on. It needs Claude Code 2.1.214 or later. An application built on Claude Code's SDK, such as the Claude desktop app, is handed each such call to approve and is expected to show it to a person; check that yours does before you rely on it. It is a Claude Code feature, not a guarantee: the mark is Claude Code's own, and any other MCP client ignores it and asks as its own rules say.Without it, Claude Code's own rules can keep a person on these tools, in
.claude/settings.json. Anaskrule prompts in every permission mode, auto mode included, and comes before anyallowrule, a "don't ask again" one included; anallowrule lets an agent post on its own (Claude Code permissions). With the server registered asmattermost:{ "permissions": { "ask": [ "mcp__mattermost__create_post", "mcp__mattermost__dm", "mcp__mattermost__group_message", "mcp__mattermost__update_post", "mcp__mattermost__delete_post", "mcp__mattermost__add_reaction", "mcp__mattermost__remove_reaction", "mcp__mattermost__pin_post", "mcp__mattermost__join_channel", "mcp__mattermost__leave_channel", "mcp__mattermost__add_channel_members", "mcp__mattermost__create_channel", "mcp__mattermost__set_status", "mcp__mattermost__delete_draft" ] } } MM_MCP_MARK_AI_GENERATED- Optional,
trueby default. Every post and edit the model writes carries Mattermost's own marker for text written with AI, which its web app shows beside the post's time (ADR-031).falseleaves it out. MM_MCP_POST_FROM_VIEWS- Optional,
trueby default. In an AI app that shows mm-mcp's views, a post the model proposes withpropose_postshows as it will be posted, with Post, and your press posts it, marked as written with AI (ADR-035).falsetakes Post out of the view, and the draft waits in Mattermost for you to send. It is for an app that cannot be trusted to keep the view's own tool from its model, or to press only when you click. It does not followMM_MCP_ELICITATION_OPT_IN: a press is never asked about, so where every post should wait for a question, set this tofalseas well. MM_MCP_DOWNLOAD_DIR- Optional. The directory
save_filewrites attachments to, when the server runs over stdio on your own machine. Your Downloads directory by default. An existing file is never overwritten (ADR-029). MM_MCP_CA_FILE- Optional. A PEM file of certificate authorities to trust beside your
system's own, for a Mattermost whose certificate your organisation signed
itself.
mm-mcp serve,login,logoutanddoctorall trust it; set it in your terminal formm-mcp loginas in your MCP client for the server. A file that cannot be read, or holds no certificate, stopsserve,loginandlogoutat start and says so, anddoctorreports it. MM_MCP_RESOURCE_MAX_MB- Optional,
10by default. The most the one message that carries a file read as an MCP resource holds, in megabytes of 1,048,576 bytes, a binary file counted as its base64, a third larger than the file. MCP sends a resource whole, in one message, and an MCP client drops a message past its own limit, and with it the request or the whole session: the TypeScript SDK's stdio transport, which many clients are built on, takes 10 MiB, and Go's 16 MiB. A file whose message would be larger is refused before it is sent, withread_fileandsave_fileas the ways to read it (ADR-029). Raise it to what your client takes;0is no limit. The file a resource read downloads is bounded by Mattermost's own Maximum File Size, which every upload was within; a file past it, most likely attached before an administrator lowered it, is refused before it is downloaded. MM_MCP_BLOCK_EXTERNAL_NETWORK- For mm-mcp's own tests. While it is
1, mm-mcp refuses to reach any address but the loopback ones (ADR-006). Leave it unset.
Through a proxy¶
mm-mcp reaches Mattermost through the proxy the standard variables name:
HTTPS_PROXY for an https address, HTTP_PROXY for an http one, and
NO_PROXY for the hosts to reach directly. mm-mcp serve, login, logout
and doctor all read them, and doctor says which proxy, if any, a request to
your server goes through. Set them where each runs: in your MCP client's
configuration for the server, and in your terminal for mm-mcp login.
Command line¶
mm-mcp serve- Runs the server over stdio, for a client that starts it as a process.
mm-mcp serve --transport http [--host 127.0.0.1] [--port 8765]- Runs it over Streamable HTTP, on a loopback address only.
mm-mcp login [--url https://chat.example.com] [--with oauth|window|password|paste] [--browser path] [--client-id id] [--callback-port 8766]-
Logs you in the way the server allows, checks the session with Mattermost, and keeps it in your system's credential store for that server: OAuth in your own browser, a browser window of its own for single sign-on, your password in the terminal, or a token you paste (Logging in).
--withpicks one way,--browserthe browser for a window, and--client-idthe OAuth app an administrator registered for mm-mcp, whose callback is on--callback-port.--urlisMM_URLwhen not given (ADR-019).--with pastekeeps a personal access token or a bot's token the same way, so it need not sit in your MCP client's configuration. On success it printsLogged in to … as @youon standard output and exits with status 0; when no way worked, it sums up each way it tried and why it failed, on standard error, and exits with status 1; a wrong flag exits with status 2. mm-mcp logout [--url https://chat.example.com]- Forgets the stored login. A session mm-mcp made itself, through OAuth, its browser window or your password, it also ends at Mattermost. A token you pasted it only forgets: it may be your browser's own session, or a personal access token you revoke under Profile > Security.
mm-mcp doctor [--url https://chat.example.com] [--json]- Checks what mm-mcp needs, and says what to fix for each check that fails:
every variable above, the login
mm-mcp loginstored for the address and whetherMM_TOKENhides it, the proxy, whether the server answers as a supported Mattermost, whose credential it is and whether that user belongs to a team, and howmm-mcp loginwould log you in there, with the browsers a login window could use. It reads the terminal's environment, which is not your MCP client's:--urlnames the server, and thediagnosetool (Tools) checks the client's own configuration from inside it. It changes nothing, and never prints the credential; it does print the address and your username.--jsongives the checks to an agent. It exits with status 1 when a check failed. mm-mcp version- Prints the installed version.
mm-mcp help- Prints the commands and where the configuration comes from.
--helpand-hdo the same.
A configuration error exits with status 2 and says which setting is wrong.
Before it serves, mm-mcp serve asks Mattermost who the token belongs to, and
says so in the client's log. A token Mattermost refuses, or an address that
does not answer as Mattermost, stops it with status 2 and what to fix. A server
it cannot reach is only warned about, and the tools say so until it can be
reached. A server older than the oldest supported release
(Supported Mattermost releases) is warned about too.
These are the checks mm-mcp doctor makes of the server, so the two agree.