# 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

```bash
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

```bash
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

```bash
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:

```bash
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:

```bash
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:

```json
{
  "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.