discord-ops

Agency-grade Discord MCP server with multi-guild project routing.

• 48 MCP tools — messaging, channels, moderation, roles, webhooks, audit log, threads, guilds, invites, permissions, search, 23 templates, OG embed unfurling, project introspection
• Multi-guild project routing — send_message({ project: "my-app", channel: "builds" }) instead of raw channel IDs
• Notification routing — map notification types (ci_build, deploy, error) to channels per project
• Owner pings — configure project owners so releases, errors, and alerts auto-mention the right people
• Multi-bot support — manage multiple Discord bots from a single MCP server with per-project tokens
• Tool profiles — load only the tools an agent needs; cut schema overhead by 85% with slim profiles
• Smart channel resolution — channel params accept channel name or snowflake ID, with 4-layer fuzzy fallback
• Auto-embed for send_message — every message gets a branded embed by default; raw: true for plain text
• OG metadata unfurling — send_embed fetches Open Graph metadata server-side and renders rich link previews
• Flexible token configuration — configurable default token env var, optional default when all projects use per-project tokens
• Config validation — discord-ops validate detects duplicate guilds, missing tokens, invalid channel refs without connecting to Discord
• HTTP/SSE + stdio transports — stdio for Claude Code, HTTP/SSE for remote MCP clients
• HTTP transport auth — bearer token auth via DISCORD_OPS_HTTP_TOKEN with constant-time comparison
• Dry-run mode — simulate destructive operations without calling Discord API
• Interactive setup wizard — discord-ops setup supports single-bot and multi-bot configuration
• Security hardening — rate limiting, permission pre-flight checks, snowflake ID validation, self-protection guards
• Lazy login — tools enumerate before Discord connects; first tool call triggers login
• Zod validation — all inputs validated before execution
• Error sanitization — tokens, webhook URLs, and snowflake IDs stripped from error output
• Audit logging — every tool call logged to stderr

# Install
npm install -g discord-ops

# Interactive setup (creates ~/.discord-ops.json)
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.

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

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:

1. Exact alias match — "builds" hits the builds alias in your project config
2. Fuzzy alias match — "build" or "blds" resolves to the closest alias
3. Live Discord API lookup — "general" resolves even with no configured alias
4. Error — if none of the above find a match

This 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.

{
  "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.14.0",
  project: "my-app",
  channel: "releases",
  title: "discord-ops v0.14.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.

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",
      "tool_profile_add": ["send_message"],
      "tool_profile_remove": ["list_members"]
    }
  }
}

• tool_profile — base profile to use for this project
• tool_profile_add — add tools not included in the base profile
• tool_profile_remove — remove tools from the base profile

discord-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 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

The 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.

1. 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).
2. Otherwise, the default token comes from DISCORD_TOKEN.
3. Per-project tokens override the default: if a project config has "token_env": "ORG_A_TOKEN", that project's bot uses ORG_A_TOKEN.
4. If all projects have token_env set with valid values, no default token is needed at all.

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"
}

• No 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.
• Channel values are Discord snowflake IDs. Channel names (aliases) resolve to these IDs.

Store two secrets in your repo:

• BOOKED_DISCORD_BOT_TOKEN — your bot token
• DISCORD_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 branding — every template has a configurable author_name + author_icon at the top
• Link buttons — clickable buttons below embeds (View Logs, Open PR, Runbook, etc.)
• Discord timestamps — dates auto-convert to each user's timezone with live countdowns
• Native polls — real Discord polls with progress bars and vote tracking
• Multi-embed dashboards — up to 10 embeds per message for service status boards
• Footer icons — status indicator icons (green/red) next to footer text
• Clickable titles — embed titles link directly to URLs
• Syntax-highlighted code — code examples with language-specific highlighting
• Progress bars — visual Unicode block progress indicators

Release announcement:

send_template({
  template: "release",
  vars: {
    version: "v0.14.0",
    name: "discord-ops",
    highlights: "• Owner pings\n• Smart channel resolution\n• Category channel editing",
    npm: "npm install discord-ops@0.14.0",
    npm_url: "https://www.npmjs.com/package/discord-ops/v/0.14.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:

{
  "projects": {
    "my-app": {
      "guild_id": "123456789012345678",
      "token_env": "MY_APP_DISCORD_TOKEN",
      "channels": {
        "dev": "CHANNEL_ID",
        "builds": "CHANNEL_ID",
        "releases": "CHANNEL_ID",
        "alerts": "CHANNEL_ID"
      },
      "default_channel": "dev"