Mattermost MCP server

A custom MCP connector that lets Claude (including scheduled Cowork tasks, from any device) fetch an RSS feed and post messages to your self-hosted Mattermost server at https://mattermost.your-domain.example.

It runs as a remote HTTP server on your VPS, fronted by nginx + HTTPS, and authenticates Claude with OAuth 2.1 (Dynamic Client Registration + PKCE) — the scheme Claude's "Add custom connector" dialog actually supports. (Claude does not support user-pasted static bearer tokens for custom connectors, which is why OAuth is required here.)

Why a connector at all

Claude's built-in sandbox can only reach an allowlist of domains and cannot reach your private Mattermost server. The MCP server runs on infrastructure you control, so it talks to Mattermost directly. Claude still makes the fetching decisions and does the summarizing/analysis; the connector just provides the fetch_rss and post_* actions.

Tools exposed

• whoami — verify the bot token (auth/connectivity check).
• fetch_rss(feed_url, max_articles=5) — fetch and parse an RSS/Atom feed.
• post_to_channel(channel, message, team=None) — post to a channel.
• post_to_user(username, message) — send a direct message.

Files

• server.py — MCP server (stdio + HTTP transports, pluggable auth).
• auth.py — self-contained OAuth 2.1 authorization server.
• requirements.txt — Python dependencies.
• mattermost-mcp.env.example — env template for the VPS.
• mattermost-mcp.service — systemd unit.
• nginx-mattermost-mcp.conf — nginx HTTP reverse proxy (certbot-ready).
• Caddyfile.example — alternative HTTPS reverse-proxy config.

---

1. Mattermost bot token

System Console → Integrations → Bot Accounts → create a bot → copy its Access Token. Add the bot to the team (YOUR-TEAM) and the channel (YOUR-CHANNEL). The token needs permission to create posts.

If you pasted a token into a chat earlier, rotate it and use only the fresh one here.

2. Install on the VPS

sudo useradd --system --create-home --home-dir /opt/mattermost-mcp mcp
sudo install -d -o mcp -g mcp /opt/mattermost-mcp
# copy server.py, auth.py, requirements.txt into /opt/mattermost-mcp/
sudo -u mcp python3 -m venv /opt/mattermost-mcp/.venv
sudo -u mcp /opt/mattermost-mcp/.venv/bin/pip install -r /opt/mattermost-mcp/requirements.txt

3. Configure

sudo cp mattermost-mcp.env.example /etc/mattermost-mcp.env
sudo nano /etc/mattermost-mcp.env
sudo chown mcp:mcp /etc/mattermost-mcp.env
sudo chmod 600 /etc/mattermost-mcp.env

Set at minimum:

• MATTERMOST_TOKEN — the fresh bot token.
• MCP_AUTH=oauth
• MCP_ISSUER=https://mcp.your-domain.example — must exactly match the public hostname you serve over HTTPS (scheme + host, no trailing slash).
• MCP_OWNER_PASSWORD — the password you'll type on the consent screen when connecting Claude. Generate a strong one: openssl rand -base64 24.
• MCP_OAUTH_DB=/var/lib/mattermost-mcp/oauth.db — persisted by the unit's StateDirectory, so connections survive restarts.

The server binds to 127.0.0.1:8000; nginx is the public front door.

4. Run as a service

sudo cp mattermost-mcp.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now mattermost-mcp
curl http://127.0.0.1:8000/healthz        # -> ok

5. HTTPS front door (nginx + certbot)

Point a DNS A record (mcp.your-domain.example) at the VPS, then:

sudo cp nginx-mattermost-mcp.conf /etc/nginx/sites-available/mattermost-mcp
sudo ln -s /etc/nginx/sites-available/mattermost-mcp /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d mcp.your-domain.example      # adds the 443/SSL block in place

The supplied nginx config sets proxy_http_version 1.1, proxy_buffering off, and a long read timeout — required, or the streamed (SSE) MCP responses stall. (Caddy alternative: Caddyfile.example.)

Sanity-check the OAuth discovery endpoints from your laptop:

curl https://mcp.your-domain.example/healthz
curl https://mcp.your-domain.example/.well-known/oauth-protected-resource
curl https://mcp.your-domain.example/.well-known/oauth-authorization-server

Allowlisting note: Claude's servers connect to yours from the public internet, originating from 160.79.104.0/21. If you firewall the MCP host, allow that range.

6. Add the connector in Claude

This is the part that confused you — there are two different features:

• Developer tab → "Local MCPs" edits claude_desktop_config.json and is only for local stdio servers. Not what you want here.
• Settings → Connectors → "Add custom connector" is for remote servers. Use this one.

Steps:

1. Settings → Connectors → scroll down → Add custom connector.
2. URL: https://mcp.your-domain.example/mcp
3. Leave OAuth Client ID/Secret blank — the server supports Dynamic Client Registration, so Claude registers itself automatically.
4. Click Add. Claude opens the consent screen served by your server; enter your MCP_OWNER_PASSWORD and click Allow.
5. Claude completes the OAuth exchange and the mattermost tools appear.

Because Claude connects from its cloud (not your device), this works from the desktop app, web, and mobile alike.

7. Test it

Ask Claude:

1. "Use the mattermost connector's whoami tool." → returns the bot username.
2. "Fetch 5 items from https://news.ycombinator.com/rss and post a bullet summary of each to the YOUR-CHANNEL channel."

8. Then schedule it

Once a manual post works, ask Claude to create the scheduled task that runs fetch_rss → summarize → post_to_channel at 8am, 1pm, 4pm, 6pm, 8pm and 10pm daily. Note: a Cowork scheduled task only fires while the Claude app is running on some device; the connector itself stays up on the VPS regardless. For a fully device-independent schedule, a cron job on the VPS calling the Anthropic API directly is the alternative.

---

Security model

• OAuth 2.1 + PKCE gate the MCP endpoint; only /healthz and the OAuth discovery/registration endpoints are open. Every connection requires entering MCP_OWNER_PASSWORD on the consent screen.
• Access tokens expire (1h) and refresh-tokens rotate on use; revoke everything by deleting oauth.db and restarting.
• HTTPS (via nginx/certbot) protects tokens in transit.
• MATTERMOST_TOKEN authorizes posting to Mattermost and never leaves the VPS. Scope the bot to only the channels it needs.
• Keep /etc/mattermost-mcp.env at chmod 600.

Local (stdio) alternative

For a single machine without hosting, add to claude_desktop_config.json (Developer tab) and skip OAuth entirely:

{
  "mcpServers": {
    "mattermost": {
      "command": "/abs/path/mattermost-mcp/.venv/bin/python",
      "args": ["/abs/path/mattermost-mcp/server.py"],
      "env": {
        "MATTERMOST_URL": "https://mattermost.your-domain.example",
        "MATTERMOST_TOKEN": "YOUR_BOT_TOKEN",
        "MATTERMOST_TEAM": "YOUR-TEAM"
      }
    }
  }
}

(MCP_TRANSPORT defaults to stdio.) This only works on that machine while Claude is running.

Bearer mode (testing only)

Set MCP_AUTH=bearer and MCP_API_KEY=... to gate the HTTP server with a static token — useful for curl/inspector testing, but not usable from Claude's custom-connector dialog.