discord-ops
Agency-grade Discord MCP server with multi-guild project routing.
接入你的智能体
從發布者安裝。不是 PlugMCP 端點。
遠端 URL 還是本機指令? 兩種安裝方式的差異
discord-ops listen sidecar streams messages/reactions to a local sink read by get_events, zero API calls per pollsend_message({ project: "my-app", channel: "builds" }) instead of raw channel IDsget_replies / get_reactions — Discord as a durable coordination busci_build, deploy, error) to channels per projectraw: true for plain textsend_embed fetches Open Graph metadata server-side and renders rich link previewsdiscord-ops validate detects duplicate guilds, missing tokens, invalid channel refs without connecting to DiscordDISCORD_OPS_HTTP_TOKEN with constant-time comparisondiscord-ops setup discovers guilds/channels live, configures single/multi-bot routing and the coordination board, and writes a project .mcp.json for one-command install# Install
npm install -g discord-ops
# Interactive setup — connects to your bot, discovers guilds/channels, and
# writes ~/.discord-ops.json + a project .mcp.json (so Claude Code loads it)
discord-ops setup
# Or manual setup
export DISCORD_TOKEN="your-bot-token"
discord-ops health
# Start MCP server (stdio)
discord-ops
# Start MCP server (HTTP/SSE)
discord-ops serve --port 3000
Add to your project's .mcp.json. Use npx with @latest so every session automatically uses the latest published release — without it, npx may serve a stale cached version indefinitely:
{
"mcpServers": {
"discord-ops": {
"command": "npx",
"args": ["-y", "discord-ops@latest"],
"env": {
"DISCORD_TOKEN": "${DISCORD_TOKEN}"
}
}
}
}
The ${VAR} syntax is Claude Code's native env var interpolation — it reads the value from your shell environment at startup. Export your bot token in ~/.zshrc (or .bashrc) and it will be available to all projects without hardcoding it in any file.
When each project has its own bot, pass all token env vars and let ~/.discord-ops.json handle which project uses which:
{
"mcpServers": {
"discord-ops": {
"command": "npx",
"args": ["-y", "discord-ops@latest"],
"env": {
"ORG_A_DISCORD_TOKEN": "${ORG_A_DISCORD_TOKEN}",
"ORG_B_DISCORD_TOKEN": "${ORG_B_DISCORD_TOKEN}"
}
}
}
}
Each project in ~/.discord-ops.json declares "token_env": "ORG_A_DISCORD_TOKEN" and discord-ops routes automatically. No default DISCORD_TOKEN needed when all projects have token_env set.
If all your projects share one bot, just pass that token:
{
"mcpServers": {
"discord-ops": {
"command": "npx",
"args": ["-y", "discord-ops@latest"],
"env": {
"DISCORD_TOKEN": "${DISCORD_TOKEN}"
}
}
}
}
If another tool already claims DISCORD_TOKEN, use DISCORD_OPS_TOKEN_ENV to point at a different name:
{
"mcpServers": {
"discord-ops": {
"command": "npx",
"args": ["-y", "discord-ops@latest"],
"env": {
"DISCORD_OPS_TOKEN_ENV": "MY_BOT_TOKEN",
"MY_BOT_TOKEN": "${MY_BOT_TOKEN}"
}
}
}
}
The killer feature: route messages by project name and channel alias instead of raw IDs.
~/.discord-ops.json){
"projects": {
"my-app": {
"guild_id": "123456789012345678",
"channels": {
"dev": "CHANNEL_ID",
"builds": "CHANNEL_ID",
"alerts": "CHANNEL_ID",
"releases": "CHANNEL_ID"
},
"default_channel": "dev"
}
},
"default_project": "my-app",
"notification_routing": {
"ci_build": "builds",
"deploy": "builds",
"release": "releases",
"error": "alerts",
"dev": "dev"
}
}
Projects can specify their own bot token via token_env:
{
"projects": {
"org-a": {
"guild_id": "111111111111111111",
"channels": { "dev": "CHANNEL_ID" },
"default_channel": "dev",
"token_env": "ORG_A_DISCORD_TOKEN"
},
"org-b": {
"guild_id": "222222222222222222",
"channels": { "dev": "CHANNEL_ID" },
"default_channel": "dev",
"token_env": "ORG_B_DISCORD_TOKEN"
}
}
}
When all projects have token_env, the default DISCORD_TOKEN is optional. Each project connects with its own bot.
Give bots names, roles, and per-channel assignment. This is ideal when your Discord server runs multiple bots with distinct personas (e.g., a community helper vs. a tech ops bot).
{
"bots": {
"claire": {
"name": "Claire",
"role": "Community helper",
"description": "Handles support and community channels",
"token_env": "CLAIRE_TOKEN",
"default_profile": "messaging"
},
"courier": {
"name": "Clarity Courier",
"role": "Technical operations",
"token_env": "COURIER_TOKEN",
"default_profile": "full",
"profile_add": ["send_template"],
"profile_remove": []
}
},
"projects": {
"clarity-house": {
"guild_id": "123456789012345678",
"bot": "courier",
"channels": {
"general": "111111111111111111",
"support": { "id": "222222222222222222", "bot": "claire" },
"dev-ops": "333333333333333333",
"ai-testing": { "id": "444444444444444444", "bot": "claire" }
},
"default_channel": "dev-ops",
"tool_profile": "full"
}
}
}
How it works:
bots — named bot definitions with identity metadata and token_envproject.bot — default bot for the project (all channels use this bot unless overridden)bot override — individual channels can use a different bot: { "id": "...", "bot": "claire" }default_profile — per-bot tool profile (restricts which tools a bot can use at runtime)profile_add — additional tools to load on top of the bot's default_profileprofile_remove — tools to exclude from the bot's default_profiletoken_env → default DISCORD_TOKENbot: { name, role } metadata for agent contextbots is optional; channels accept both "ID" and { "id": "ID", "bot": "name" } formatsUse list_bots to see all configured bots, their project assignments, channel overrides, and connection status.
Configure project owners so that releases, errors, and alerts automatically prepend @mentions. This ensures the right people are always paged for critical events without hardcoding mentions in every message.
{
"projects": {
"my-app": {
"guild_id": "123456789012345678",
"channels": { "releases": "CHANNEL_ID", "alerts": "CHANNEL_ID" },
"owners": ["820027414902079548"],
"notify_owners_on": ["release", "error", "alert"]
}
}
}
notify_owners_on values: any notification type (release, error, alert, ci_build, deploy, etc.)
Safety: "dev" is hardcoded to never trigger owner pings regardless of config — dev noise stays quiet.
When a send_message or send_embed call uses a matching notification_type, the owner mentions are automatically prepended to the message. No other changes needed.
The channel param accepts a channel name or snowflake ID anywhere a channel is needed. Resolution happens in four layers:
"builds" hits the builds alias in your project config"build" or "blds" resolves to the closest alias"general" resolves even with no configured aliasThis means you can pass channel: "general" and it will work even for channels that aren't in your config. You can also pass a raw snowflake ID directly — channel: "1234567890" bypasses alias resolution entirely.
.discord-ops.json in repo root){
"project": "my-app",
"notification_routing": {
"ci_build": "builds",
"deploy": "builds"
}
}
# By project + channel alias
send_message({ project: "my-app", channel: "builds", content: "Build passed!" })
# By notification type (auto-routed to channel, owner pinged if configured)
send_message({ project: "my-app", notification_type: "release", content: "v1.0.0 shipped" })
# Direct channel ID (always works)
send_message({ channel_id: "123456789", content: "Hello" })
# Channel by name (live lookup — no alias needed)
send_message({ project: "my-app", channel: "general", content: "Hello" })
send_message automatically wraps messages in a polished embed with a color bar, description, and timestamp. Pass raw: true to send plain text instead.
# Branded embed (default)
send_message({ project: "my-app", channel: "dev", content: "Deploy complete" })
# Plain text
send_message({ project: "my-app", channel: "dev", content: "pong", raw: true })
send_embed fetches Open Graph metadata server-side from any URL and renders a rich preview embed. All OG fields can be overridden.
send_embed({
url: "https://www.npmjs.com/package/discord-ops/v/0.23.0",
project: "my-app",
channel: "releases",
title: "discord-ops v0.23.0",
description: "Owner pings, smart channel resolution, category editing",
color: 5763719,
footer: "Released April 3, 2026"
})
Useful for sharing GitHub PRs, npm releases, blog posts, or any URL with rich previews — the bot fetches the metadata so Discord's CDN doesn't cache-bust client-side unfurls.
discord-ops doubles as a coordination bus for multi-agent systems. One agent posts a task as a message, peer agents (or humans) reply and react, and the originating agent reads the replies and reactions back. Because the exchange lives in Discord, it's durable across sessions, works between agent processes that share no memory, and every step is observable by the humans in the server.
The loop is four tool calls:
# Agent A posts a task and records the returned message ID
send_message({ project: "my-app", channel: "engineering", content: "TASK: verify the staging deploy", raw: true })
→ { "id": "333333333333333333" }
# Agent B claims it with a reaction, then replies
add_reaction({ project: "my-app", channel: "engineering", message_id: "333333333333333333", emoji: "👀" })
send_message({ project: "my-app", channel: "engineering", reply_to: "333333333333333333", content: "RESULT: verified, all checks green", raw: true })
# Agent A collects results at its next task boundary
get_replies({ project: "my-app", channel: "engineering", message_id: "333333333333333333" })
get_reactions({ project: "my-app", channel: "engineering", message_id: "333333333333333333" })
Three read-side tools close the loop: get_message fetches a single message with its reply, thread, and reaction state; get_reactions reports who reacted with what; get_replies collects replies to a specific message. get_messages includes reply_to on every message, so scanning agents can reconstruct conversation structure. For exchanges longer than one round trip, create_thread from the original message keeps the channel clean.
See docs/agent-coordination.md for the full protocol — reaction vocabulary, threads, polling guidance, multi-project setups, and anti-patterns. New to discord-ops? docs/project-onboarding.md is the start-to-finish walkthrough for adopting it as a team's coordination bus — project setup, the shared note board, personas, polls and forums, and least-privilege profiles.
One bot, unlimited posting identities — persona identity is a per-message webhook username/avatar override, so no new Discord bots or developer-portal work are ever needed.
Forum channels as durable work queues: a post is a task, tags are status labels, archiving closes it.
Manage the bot application itself via API — no developer portal round-trips. (Creating new bot applications remains portal-only by Discord's design; use personas instead.)
A durable, directed-note log — one board channel per project — that agents read on startup and use for hand-offs across concurrent sessions. See docs/project-onboarding.md.
Load only the tools an agent needs. Reduces schema token overhead by up to 85% for narrow use cases.
# Via CLI flag
discord-ops --profile monitoring
# Load specific tools
discord-ops --tools "send_message,send_template,health_check"
# Combined (profile as base + add tools)
discord-ops --profile readonly --tools "send_message"
Profiles can be set per project in ~/.discord-ops.json so each agent gets only what it needs:
{
"projects": {
"my-app": {
"guild_id": "123456789012345678",
"channels": { "dev": "CHANNEL_ID", "alerts": "CHANNEL_ID" },
"tool_profile": "monitoring",
"profile_add": ["send_message"],
"profile_remove": ["list_members"]
}
}
}
tool_profile — base profile to use for this projectprofile_add — add tools not included in the base profileprofile_remove — remove tools from the base profilediscord-ops Start MCP server (stdio transport)
discord-ops serve Start MCP server (HTTP/SSE transport)
discord-ops run <tool> --args '{…}' Run any tool directly (no AI/MCP required)
discord-ops init Scaffold a per-project .discord-ops.json
discord-ops setup Interactive setup wizard (single + multi-bot)
discord-ops health Run health check + permission audit
discord-ops validate Validate config without connecting to Discord
discord-ops --profile Load a built-in tool profile (monitoring/readonly/moderation/full)
discord-ops --tools Load specific tools by name (comma-separated)
discord-ops --dry-run Simulate destructive operations
discord-ops --help Show help
discord-ops --version Show version
run — call any tool without an AI agentThe run subcommand executes any discord-ops tool directly from the shell — no MCP client, no AI. Pass all tool input as a single JSON string via --args.
# Send a plain message
npx discord-ops@latest run send_message \
--args '{"project":"my-app","channel":"general","content":"Deployment complete."}'
# Send a rich release announcement
npx discord-ops@latest run send_template \
--args '{
"project": "my-app",
"channel": "releases",
"template": "release",
"vars": {
"name": "my-app",
"version": "v1.2.0",
"author_name": "My Org",
"highlights": "• New feature A\n• Bug fix B",
"npm": "my-app@latest",
"npm_url": "https://www.npmjs.com/package/my-app",
"link": "https://github.com/my-org/my-app/releases/tag/v1.2.0",
"footer": "Published 2026-04-03"
}
}'
Any tool name accepted by the MCP server works here — send_message, send_template, send_embed, list_channels, etc. The same input schema applies; validation errors are printed with field paths and exit code 1.
init — scaffold a per-project configThe init subcommand creates a .discord-ops.json file in the current directory for per-project configuration.
discord-ops init --project my-app --guild-id 123456789012345678
# With channels and custom token env var
discord-ops init --project my-app --guild-id 123456789012345678 \
--token-env MY_APP_TOKEN \
--channel builds=987654321098765432 \
--channel releases=111222333444555666
# Overwrite existing and mark as default project
discord-ops init --project my-app --guild-id 123456789012345678 --force --default
Flags:
serve flagsThe serve subcommand accepts additional flags for HTTP transport configuration:
bot override, use that bot's token_envbot, use that bot's token_envtoken_env — project's own token env varDISCORD_TOKEN (or custom via DISCORD_OPS_TOKEN_ENV)If DISCORD_OPS_TOKEN_ENV is set, its value names the env var holding the default token (e.g., DISCORD_OPS_TOKEN_ENV=MY_BOT_TOKEN reads MY_BOT_TOKEN). If all projects have token_env or bot set, no default token is needed.
Use discord-ops run in GitHub Actions (or any CI) to post rich Discord notifications after a publish, deploy, or build — no AI agent required.
In CI you typically have one bot token and one project. Pass a minimal config as an inline JSON string via DISCORD_OPS_CONFIG. No file writing needed.
When storing as a GitHub secret, minify to a single line — multiline strings break secret injection. The shape (pretty-printed for readability):
{
"projects": {
"my-app": {
"guild_id": "123456789012345678",
"channels": {
"releases": "987654321098765432",
"builds": "111222333444555666"
},
"default_channel": "releases"
}
},
"default_project": "my-app"
}
token_env needed — omitting it means the project uses DISCORD_TOKEN (the default).owners and notify_owners_on are optional — include them if you want owner pings on errors.Store two secrets in your repo:
BOOKED_DISCORD_BOT_TOKEN — your bot tokenDISCORD_OPS_CONFIG — the config JSON minified to a single line (multiline strings break GitHub secrets){"projects":{"my-app":{"guild_id":"123456789012345678","channels":{"releases":"987654321098765432"},"default_channel":"releases"}},"default_project":"my-app"}
- name: Notify Discord
run: |
npx discord-ops@latest run send_template --args '{
"project": "my-app",
"channel": "releases",
"template": "release",
"vars": {
"name": "my-app",
"version": "${{ steps.version.outputs.version }}",
"author_name": "My Org",
"highlights": "${{ steps.changelog.outputs.highlights }}",
"npm": "my-app@latest",
"npm_url": "https://www.npmjs.com/package/my-app",
"link": "${{ steps.release.outputs.url }}",
"footer": "Published ${{ steps.date.outputs.date }}"
}
}'
env:
DISCORD_TOKEN: ${{ secrets.BOOKED_DISCORD_BOT_TOKEN }}
DISCORD_OPS_CONFIG: ${{ secrets.DISCORD_OPS_CONFIG }}
DISCORD_TOKEN is the default token variable — no additional configuration needed. The bot token from your secret is used directly.
When running discord-ops serve, the HTTP endpoint is unauthenticated by default with a loud startup warning. Set DISCORD_OPS_HTTP_TOKEN to require bearer auth:
DISCORD_OPS_HTTP_TOKEN=your-secret-token discord-ops serve --port 3000
All requests must include:
Authorization: Bearer your-secret-token
The health endpoint (GET /health) is always exempt from auth — load balancers and Docker healthchecks can reach it without a token.
Token comparison uses constant-time comparison to prevent timing attacks.
Enable dry-run to simulate destructive operations (delete, ban, kick, etc.) without actually calling the Discord API:
# Via CLI flag
discord-ops --dry-run
# Via environment variable
DISCORD_OPS_DRY_RUN=1 discord-ops
# Via env alias
DRY_RUN=true discord-ops
In dry-run mode, destructive tools return a simulated success response showing what would have happened.
23 built-in templates with cutting-edge Discord features. Use send_template with project routing.
Features across all templates:
author_name + author_icon at the topRelease announcement:
send_template({
template: "release",
vars: {
version: "v0.23.0",
name: "discord-ops",
highlights: "• Owner pings\n• Smart channel resolution\n• Category channel editing",
npm: "npm install [email protected]",
npm_url: "https://www.npmjs.com/package/discord-ops/v/0.23.0",
link: "https://github.com/bookedsolidtech/discord-ops/pull/20",
footer: "Released April 3, 2026",
author_name: "Booked Solid Technology"
},
project: "my-app",
channel: "releases"
})
Native Discord Poll:
send_template({
template: "poll",
vars: {
question: "Best language for MCP servers?",
options: "TypeScript|Rust|Go|Python",
duration: "48",
multiselect: "true"
},
project: "my-app",
channel: "dev"
})
Multi-Embed Status Dashboard:
send_template({
template: "dashboard",
vars: {
services: "API|Database|CDN|Auth|Queue",
statuses: "operational|operational|degraded|operational|outage",
title: "Production Status",
url: "https://status.example.com"
},
project: "my-app",
channel: "alerts"
})
On-call handoff:
send_template({
template: "oncall",
vars: {
outgoing: "alice",
incoming: "bob",
shift_start: "2026-04-04T09:00:00Z",
notes: "Payment service latency elevated — watch grafana/d/payments",
active_incidents: "INC-342: elevated error rate on /checkout",
runbook_url: "https://wiki.example.com/oncall",
mention: "<@BOB_USER_ID>"
},
project: "my-app",
channel: "team-chat"
})
All templates support project routing (project, channel, notification_type, channel_id) and author branding (author_name, author_icon).
Full ~/.discord-ops.json schema with all options:
{
"bots": {
"my-bot": {
"name": "My Bot",
"role": "General purpose",
"description": "Handles all operations",
"token_env": "MY_BOT_TOKEN",
"default_profile": "full",
"profile_add": [],
"profile_remove": []
}
},
"projects": {
"my-app": {
"guild_id": "123456789012345678",
"token_env": "MY_APP_DISCORD_TOKEN",
"bot": "my-bot",
"channels": {
"dev": "CHANNEL_ID",
"builds": "CHANNEL_ID",
"releases": "CHANNEL_ID",
"alerts": "CHANNEL_ID",
"support": { "id": "CHANNEL_ID", "bot": "my-bot" }
},
"default_channel": "dev",
"owners": ["USER_SNOWFLAKE_ID"],
"notify_owners_on": ["release", "error", "alert"],
"tool_profile": "full",
"profile_add": [],
"profile_remove": []
}
},
"default_project": "my-app",
"notification_routing": {
"ci_build": "builds",
"deploy": "builds",
"release": "releases",
"error": "alerts",
"dev": "dev"
}
}
Global fields:
Project fields:
Per-project profiles are enforced at runtime — all tools stay registered on the MCP server, but tool calls are filtered when the resolved project or bot has a profile set. This means agents can discover all tools via MCP schema, but per-project restrictions are applied on each call.
Run discord-ops validate to check your config without connecting to Discord. It detects:
token_env values (env var not set)project.bot, channel bot) pointing to undefined botsdefault_profile or tool_profile valuestoken_env environment variablesdefault_channel referencing a nonexistent aliasdefault_project pointing to a nonexistent project"No token available for project X" The project needs a token. Either:
token_env env var (e.g., export ORG_A_TOKEN=...)DISCORD_TOKENDISCORD_OPS_TOKEN_ENV to point at a custom env varBot can't access a guild
If a project uses token_env for a different bot, that bot must be invited to the project's guild. Run discord-ops health to see which guilds each bot can access.
Migrating from single-bot to multi-bot
token_env to projects that need their own botdiscord-ops validate to verifydiscord-ops health to test connectionsToken rotation
Update the env var value and restart the MCP server. No config changes needed — token_env reads from the environment at runtime.
Channel not found
Channel resolution tries 4 layers in order: exact alias → fuzzy alias → live Discord name lookup → error. If a channel is still not found, verify the bot has access to the channel and list_channels returns it.
git clone https://github.com/bookedsolidtech/discord-ops.git
cd discord-ops
npm install
npm run build
npm test
# Local CI
./scripts/act-ci.sh --local
MIT
Agency-grade Discord MCP server — multi-guild project routing, AI-native notifications, and DevOps workflows for Claude Code and other AI agents
工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式,而不是 PlugMCP 代理伺服器。
這筆記錄未列出必要的環境變數。
Discord Ops 透過 stdio 在本機執行。
上次檢查時間:2026-10-27。 Agency-grade Discord MCP server — multi-guild project routing, AI-native notifications, and DevOps workflows for Claude Code and other AI agents