Cloud Discord MCP and HeadMod

Passive repeated-ping warnings

HeadMod warns a sender on their fourth message directly tagging the same human member within a rolling hour, across channels and active threads. This includes human staff. Self-mentions and bots are excluded. A warning mentions only its sender and is logged privately through the existing moderation log checks. Each sender receives at most one warning per hour; this rule does not delete messages or change member permissions.

REPEATED_MENTION_LIMIT defaults to 3 and REPEATED_MENTION_WINDOW_SECONDS defaults to 3600. Native Discord AutoMod separately controls the maximum mentions permitted in a single message.

On READY, HeadMod recovers the preceding hour from accessible text channels and active threads, at most 1000 messages per channel, and restores warning cooldowns from its own public warnings and private incident log. Recovery does not issue warnings for historical messages. Archived threads not present in the active thread cache are not recovered; their messages are still counted when received live. Failed or truncated history recovery is logged and reflected in /health as mention_protection.history_complete=false; live counting remains available. Keep a single deployed gateway process.

A Discord bot with a bearer-authenticated Model Context Protocol (MCP) endpoint at /mcp. HeadMod reports possible rule concerns to a private staff channel for human review. It does not ban, timeout, kick, or delete messages as a moderation response.

Related MCP server: AstrBot MCP

What HeadMod checks

HeadMod checks non-staff text messages in allowlisted servers. Live checks post an incident with a message link and short excerpt to the configured staff log; audit_recent_messages can scan a bounded recent history on request. A signal is a review cue, not a finding of guilt. Staff make the final decision using the published rules in #rules.

Matching normalizes Unicode, case, and whitespace, then requires whole terms or phrases. MODERATION_SAFE_PHRASES can exempt an exact whole-message phrase from one configured term match; built-in profanity still applies. HeadMod cannot inspect unsolicited DMs, reliably judge harassment or image/video content, detect exploits outside the server, or adjudicate Discord or Roblox Terms of Service. Report those matters to staff with context.

Configure Discord and secrets

Create a bot in the Discord Developer Portal. Enable the privileged Message Content intent for text inspection and the privileged Server Members intent for member join/leave features when ENABLE_MEMBER_EVENTS=true (the example default). Enable the same intents in the bot configuration. Give the bot View Channels, Read Message History, Send Messages, and Embed Links in the private #staff-room used for the moderation log. Keep @everyone and nonstaff roles and members unable to view that channel; HeadMod refuses to post incidents when they can access the log. The bot needs those read permissions in channels it monitors or audits, and Send Messages where it answers pings. Manage Messages is not required; grant it only if a later, separately approved delete feature is added. Existing community role and ticket features separately need Manage Roles and Manage Channels and a suitable role position.

Copy .env.example to .env, set both tokens, and keep .env out of version control:

Copy-Item .env.example .env

Set DISCORD_BOT_TOKEN to the bot token and MCP_AUTH_TOKEN to a separate long random bearer token. Set ALLOWED_GUILD_IDS to the server ID. Set RULES_CHANNEL_ID to #rules, MODERATION_LOG_CHANNEL_ID to private #staff-room, and ESCALATION_ADMIN_ID to the intended administrator's user ID. The example IDs are for the current server; replace them for a different one. A HeadMod ping containing an action word such as ban, kick, timeout, mute, delete, or punish mentions that ID only when the member currently has Administrator permission; otherwise the bot asks for a server administrator without a mention. If ALLOWED_CHANNEL_IDS is set, include the staff log ID and every channel the MCP tools should read or write. If left empty, MCP channel access is limited to the allowlisted guilds but not to a channel subset.

Set the rules channel, private moderation-log channel, and escalation administrator IDs privately for the target server before starting the bot.

Term lists are comma-separated literal terms or phrases. Add only terms staff have reviewed; leave a rule's list blank if it has no agreed terms. SPAM_WINDOW_SECONDS, SPAM_MESSAGE_THRESHOLD, and MENTION_THRESHOLD set the rule 3 thresholds; the identical-message threshold is currently fixed at three.

Run and test locally

Use Python 3.11 or newer:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
python -m pytest -q
python -c "from discord_mcp.app import create_app; print('import ok')"
python -m discord_mcp

The local endpoint is http://localhost:8000/mcp; /health reports process health and Discord readiness. The test and import commands do not need real tokens.

Deploy

Deploy Dockerfile as a web service with HTTPS and port 8000. Configure the same environment values in the provider's secret manager. MCP clients connect to the HTTPS URL ending in /mcp with Authorization: Bearer YOUR_MCP_AUTH_TOKEN.

Render's Free web service can spin down after idle time and restart later, so it cannot promise 24/7 Discord monitoring. Use an always-on service when uninterrupted monitoring matters. See Render's Free service limits.

MCP tools

• list_servers, get_channels, read_messages, and get_server_stats read allowlisted server data.

• list_moderation_flags reads HeadMod incident embeds from the configured private staff log.

• audit_recent_messages returns rule candidates from up to 50 recent messages in an allowlisted channel.

• audit_server reports permission concerns without changing them.

• send_message sends only to an allowlisted channel and requires confirm=true.

• create_channel and edit_channel create, rename, describe, move and reorder channels or categories; writes require confirm=true. Existing channel permissions are preserved. Creation is disabled when ALLOWED_CHANNEL_IDS restricts the server to a channel subset.

• get_roles reads roles. create_role adds a label with no permissions, and style_role changes color, member-list grouping or position below HeadMod. Both writes require confirm=true; they cannot assign staff powers or change role permissions.

Create a channel called roles or 🏷️・roles to publish HeadMod's role directory with persistent optional-role buttons on startup. Owner, Admin, Moderator and Developer roles remain assigned by authorized staff. Emoji prefixes and decorative category headings are supported by welcome, departure, ticket and server-discovery lookups.

MCP channel reads stay within ALLOWED_GUILD_IDS and, when configured, ALLOWED_CHANNEL_IDS. The bot's community commands also provide optional roles and private tickets; closing a ticket deletes that ticket channel.