Discord MCP Server

Discord MCP

Discord MCP is a local stdio Model Context Protocol server for safe Discord guild and separately allowlisted one-to-one access through an operator-owned bot. It combines broad typed coverage with exact scope, privacy-minimized results, reviewed writes, content-free evidence, and explicit ambiguity handling.

Least privilege. Review before mutation. Verifiable outcomes. No Discord-content persistence.

Quick start | Capability map | Safety model | Trust and verification | Complete reference | Security

Why this connector

The complete reference documents every tool family, policy gate, permission boundary, privacy tier, resource, prompt, Gateway mode, operator command, and known limitation.

Quick start

Requirements:

• Node.js 22 or newer
• A Discord application with a bot user
• One strict non-secret JSON policy file
• The bot token available through an environment variable or protected file
• Only the Discord permissions needed for the selected read or reviewed-write scope

Each deployment uses a Discord application and bot controlled by that operator. Discord MCP does not provide a shared bot, hosted relay, or shared token: create your own application, invite its bot only to guilds you control, and keep its credential in the local launcher or secret store.

Do not grant the bot Administrator. Generate the exact initial permission grant from a read-only preset, then narrow the installed bot role with category or channel overrides. The bot setup guide explains bot ownership, optional intents, and later feature-specific permissions.

Inspect before connecting

For an exact published version, inspect the real production contract and the recommended read-only preset without a token or Discord request:

npx --yes @j-256/discord-mcp@0.1.1 catalog --check
npx --yes @j-256/discord-mcp@0.1.1 catalog --html ./discord-mcp-contract.html
npx --yes @j-256/discord-mcp@0.1.1 preset show server-observer

catalog --check launches a credential-free, execution-disabled MCP server, negotiates its real tools, prompts, resources, templates, completion capability, and optional plan-review MCP App, verifies every policy-completion route with zero returned identifiers, fingerprints the app's exact HTML and authority boundary, and verifies that every tool call is blocked by the catalog-only guard.

catalog --html FILE writes a deterministic standalone explorer for that same negotiated contract. Open it locally to search and filter every tool, inspect exact input and output schemas, review prompts, resources, policy-completion routes, and the complete plan-review app source, and compare the embedded contract, safety, and app digests. The export contains no credential or identifier completion value, uses no external asset, makes no network request, and refuses to replace an existing file.

The exact release image exposes the same safe catalog without a token and defaults to catalog mode instead of operational service:

docker run --rm -i \
  --network=none \
  --read-only \
  --cap-drop=ALL \
  --security-opt=no-new-privileges:true \
  --pids-limit=64 \
  ghcr.io/j-256/discord-mcp:0.1.1 catalog --check

Install your owner-managed bot

Create a Discord application and bot in the Developer Portal, copy the public Application ID and target Server ID, and generate a callback-free install link whose guild and least-privilege permission grant come from the recommended preset:

npx --yes @j-256/discord-mcp@0.1.1 preset install server-observer \
  --application-id YOUR_APPLICATION_ID \
  --guild-id YOUR_GUILD_ID \
  --html ./discord-mcp-onboarding.html

Open the printed URL while signed in as a member allowed to manage that server. It requests only View Channel for server-observer, locks the server selector to the supplied ID, requests no user token, and never sends the bot token to the connector command. Keep Public Bot disabled unless other people should be able to install your application. Use channel-reader instead to request View Channel plus Read Message History; its plan also identifies Message Content as the recommended Developer Portal intent.

The optional --html FILE output is a deterministic standalone guide derived from that exact validated installation plan. It provides an in-memory checklist, non-secret copy controls, the explicit Discord install navigation, strict-policy commands, and exact plan evidence without accepting a token, loading an external asset, making a background request, persisting browser state, opening a browser, or replacing an existing file. The terminal plan remains complete when HTML is not wanted.

Create the safest first configuration

Keep the token in a secret-capable launching environment, verify one exact guild, save the complete non-secret policy in one file, and test the full MCP path:

export DISCORD_BOT_TOKEN="YOUR_DISCORD_BOT_TOKEN"
npx --yes @j-256/discord-mcp@0.1.1 setup \
  --config ./discord-mcp.json \
  --preset server-observer \
  --guild-id YOUR_GUILD_ID
npx --yes @j-256/discord-mcp@0.1.1 config validate ./discord-mcp.json
npx --yes @j-256/discord-mcp@0.1.1 doctor --config ./discord-mcp.json --online
npx --yes @j-256/discord-mcp@0.1.1 smoke --config ./discord-mcp.json

On PowerShell, set the token in the current process before running the same commands:

$env:DISCORD_BOT_TOKEN = "YOUR_DISCORD_BOT_TOKEN"

If the launcher, container runtime, or orchestrator mounts the token as a file, select that input instead. The path must be absolute, the file must already exist for verified setup, and --token-file cannot be combined with --token-env or an ambient DISCORD_BOT_TOKEN:

npx --yes @j-256/discord-mcp@0.1.1 setup \
  --config ./discord-mcp.json \
  --preset server-observer \
  --guild-id YOUR_GUILD_ID \
  --token-file /run/secrets/discord_bot_token

The server-observer preset exposes guild metadata, roles, permission diagnostics, connector health, content-free activity, and tool discovery. It cannot enable writes, the Gateway, telemetry export, activity persistence, or Message Content access. Setup stores the credential reference and verified public IDs, never the token value, and prints a portable stdio launch descriptor for a compatible MCP client. route_discord_goal gives every prompt-capable client one safe entry point: standard catalog discovery, bounded reads, and at most a reviewed plan for a write, never a mutation.

The versioned file is the only policy boundary. It covers identity, read scope, tools, capabilities, feature scopes, limits, local storage paths, Gateway behavior, runtime settings, and privacy-safe observability. A typical deployment has two inputs: one JSON policy file and one external bot-token secret. The bot token may be referenced through an environment variable or a strictly validated file; optional authenticated-collector headers remain environment references. The checked-in JSON Schema supports editor validation, while config show and config explain provide secret-free inspection. Managed profiles use the same document when private per-user storage is preferable.

limits.mcpReadResponseMaxBytes bounds one complete redacted MCP application read result by compact UTF-8 JSON bytes. It defaults to 1 MiB and accepts 64 KiB through 8 MiB. An oversized tool read returns a fixed content-free response-too-large error; an oversized resource or prompt fails with a fixed protocol error. The connector never clips structured JSON, emits a preview, spills withheld data, or reports the measured size. Final results from mutation-capable tools are always preserved because Discord may already have changed. Protocol discovery and notifications are outside this result boundary; use toolsets and progressive discovery to control catalog size.

Credential-authenticated Incoming-webhook messages use storage.webhookCredentialRoot, an existing canonical process-owned 0700 directory. Connector-created credentials become available through separately gated exact lookup, bounded plain-text delivery, editing, and reviewed deletion, with exclusive 0600 files and durable directory synchronization. MCP accepts no credential, execution URL, path, identity override, thread target, rich payload, file, component, poll, or raw webhook payload. Allowlist direct text or announcement channels in scopes.webhookMessageChannelIds, then enable only the required webhook-message capability.

Operational commands require --config FILE, --profile NAME, or the non-secret DISCORD_MCP_CONFIG_FILE selector. Ambient policy variables are rejected and there is no alternate environment-policy or migration mode. Running setup without a preset verifies an existing policy without rewriting it, while a preset explicitly creates or replaces the selected target.

Offline doctor remains useful before a secret is mounted or when its referenced file is unavailable. It reports credential availability as a separate failure and continues validating the strict policy, identity pins, scope, tool surface, effective read-response budget, and safety gates. doctor --online contacts Discord only when the real selected credential is available.

Review any policy replacement

Keep the active policy unchanged while editing a separate candidate, then review and apply only an exact fresh plan:

npx --yes @j-256/discord-mcp@0.1.1 config workbench \
  ./discord-mcp.json \
  --html ./discord-mcp-workbench.html
npx --yes @j-256/discord-mcp@0.1.1 config plan \
  ./discord-mcp.json \
  ./discord-mcp.candidate.json
npx --yes @j-256/discord-mcp@0.1.1 config apply \
  ./discord-mcp.json \
  ./discord-mcp.candidate.json \
  --plan-digest SHA256_FROM_THE_PLAN \
  --confirm ACTIVE_POLICY_NAME

The optional workbench validates the active schema-v2 document, then writes an exclusive private standalone editor. It embeds the complete non-secret policy, including public Discord IDs, local paths, and external secret reference names, so treat the HTML as private. Edits stay in browser memory until an explicit candidate download. The page has no secret field, network or external navigation authority, browser persistence, Discord access, active-file write, or approval authority, and it does not open a browser automatically. Its local checks and preliminary impact labels are guidance only.

Planning remains authoritative. It reads two protected non-secret documents and reports every exact field change, its authority or operational impact, canonical tool additions and removals, warnings, both document digests, the complete candidate, and structured post-application checks. It never resolves a referenced secret or contacts Discord. Application rereads both files, requires the exact digest and active-policy-name confirmation, rejects identity drift or either stale document, preserves a recoverable backup, and leaves the candidate untouched. The active document remains the only policy source; there is no legacy environment fallback or migration layer.

Review recent write outcomes and durable cross-process claims from the same selected policy without making a Discord request or resolving its credential:

npx --yes @j-256/discord-mcp@0.1.1 activity \
  --config ./discord-mcp.json \
  --html ./discord-mcp-activity.html

The bounded review collapses each activity ID into its newest current outcome while retaining older records as superseded history. Pending, uncertain, failed, drifted, malformed, and review-required evidence produces warning exit status instead of looking like a clean run. Matching reviewed operations are joined to durable claims only through both their content-free operation-key hash and plan digest, while claims without a match in the bounded window remain explicitly labeled. The digest binds the exact collected report, while its independent-read marker avoids implying that separate local files were captured under one global state lock. The optional private standalone explorer adds search and filters but cannot contact Discord, resolve a claim, retry an operation, persist browser state, or expose the selected activity-file path. Use the separate exact-confirmation coordination resolve command only after stopping the owning process and checking the exact Discord state and audit log.

Feature policy uses the same document shape. Bulk bans, bulk member-role changes, guild pruning, and other reviewed features each have separate capabilities, exact scopes, bounded limits, and documented toolsets. Single-member authority never grants batch authority. No environment-policy interface, legacy alias, fallback parser, or migration layer exists.

Use channel-reader only when bounded message history and native search are needed. It requires at least one exact channel:

npx --yes @j-256/discord-mcp@0.1.1 setup \
  --config ./discord-reader.json \
  --preset channel-reader \
  --guild-id YOUR_GUILD_ID \
  --channel-id YOUR_CHANNEL_ID

Expand the policy through review

Keep first setup read-only, then plan an additive recipe when a write workflow is needed. guild-builder adds model-neutral, caller-retained authoring and two-pass capture for guild structure, profile, settings, Community, Welcome Screen, onboarding, staged AutoMod, and static publications without storing the objective or blueprint. Its settings, Community, and onboarding evidence uses a nonprivileged GUILDS-only layout-evidence connection without changing the event feed. incident-response adds privacy-minimized incident audit and reviewed time-bounded lockdown changes with no Gateway or privileged intent. channel-publisher adds bounded text, static Components V2, and remote-free rich-embed publication and reports the required Message Content intent. direct-messenger adds exact-user reads plus reviewed text and static Components V2 delivery, same-format edits, and deletion. Optional private-file delivery requires a separate capability and owned attachment root; the recipe does not grant it. Private messaging adds no guild permission, privileged intent, Gateway feed, group DM, recipient discovery, remote-file fetch, interactive callback, or immediate write path.

npx --yes @j-256/discord-mcp@0.1.1 recipe list
npx --yes @j-256/discord-mcp@0.1.1 recipe plan guild-builder ./discord-mcp.json \
  --guild-id YOUR_GUILD_ID
npx --yes @j-256/discord-mcp@0.1.1 recipe apply guild-builder ./discord-mcp.json \
  --guild-id YOUR_GUILD_ID \
  --plan-digest SHA256_FROM_THE_PLAN \
  --confirm guild-builder
npx --yes @j-256/discord-mcp@0.1.1 recipe plan direct-messenger ./discord-mcp.json \
  --user-id EXPECTED_RECIPIENT_USER_ID
npx --yes @j-256/discord-mcp@0.1.1 recipe apply direct-messenger ./discord-mcp.json \
  --user-id EXPECTED_RECIPIENT_USER_ID \
  --plan-digest SHA256_FROM_THE_PLAN \
  --confirm direct-messenger

Planning prints the complete proposed non-secret document, exact field changes, permissions, intents, risks, warnings, and a path-bound digest without resolving a secret or contacting Discord. Application recomputes that plan, requires the exact digest and recipe-name confirmation, rejects a concurrent source change, preserves a recoverable backup, and still grants no Discord authority by itself. Run the printed offline validation, online doctor, and smoke checks after applying. Recipes add policy only; they never remove an existing capability, scope, or toolset.

Online doctor verifies identity, bounded guild membership, and application posture. Smoke launches the selected policy through the real serve entrypoint, negotiates stable MCP over stdio, validates catalogs, annotations, and read-only status, and writes nothing to Discord. Configured optional runtimes start and stop with the child; see the operator reference.

Build from source

git clone https://github.com/j-256/discord-mcp.git
cd discord-mcp
npm run deps:locked
npm run build
node dist/cli.js catalog --check

The exact installation, operator CLI, and configuration references cover standalone configuration, managed profiles, OCI bind mounts, progressive discovery, toolsets, allowlists, optional Gateway modes, observability, and every independently gated feature.

Capability map

Capabilities are exposed only when their toolset and policy gates are selected. A toolset narrows the callable surface but never grants Discord or local write authority. Browse the exact tool reference, resources, and prompts.

Safety model

Discord permissions are the outer boundary. Connector policy narrows that authority further.

• Production traffic uses fixed Discord REST and vetted Gateway origins; runtime configuration cannot redirect credentials
• Each Gateway shard counts every successful outbound event in one rolling connection budget, bounds caller-command pressure below reserved lifecycle capacity, and discards queued exact-ID requests on every connection boundary
• Exact guild, channel, role, member, and feature allowlists constrain each surface independently
• Every guild tool rejects direct and group-direct channels. The dedicated private-message tools instead require an independent exact ordinary-user allowlist and caller-known one-to-one channel IDs, support only plain text or bounded static Components V2, suppress all mentions, use fixed anti-spam limits, and provide no discovery, bulk targeting, interactive components, arbitrary embed URLs, or Gateway feed
• Discord names, messages, embeds, components, filenames, URLs, and other remote text are treated as untrusted data rather than instructions
• Discord content may be returned transiently when explicitly requested, but it is not cached, journaled, exported, or persisted by the connector
• New invite codes and URLs are delivered only through a caller-selected exclusive private file; MCP results, lifecycle records, errors, logs, and telemetry remain bearer-capability-free
• Incoming-webhook credentials remain in exclusive exact-ID private files; MCP accepts only webhook and message IDs, and persistent activity, receipts, errors, logs, and telemetry remain credential- and content-free
• Entitlement writes are separately scoped; test deletion needs creation proof, and consumption stores only a fulfillment-reference hash
• Every consequential write retains its domain-specific permission, freshness, approval, audit, readback, and uncertainty gates
• Message deletion accepts exact message IDs only and preserves every independent deletion gate
• Channel deletion requires one exact allowlisted channel, complete dependency and permission evidence, explicit irreversible-content-loss acknowledgement, signed review, and newer complete Gateway absence proof; it never reads message content to estimate impact
• Role deletion requires one exact allowlisted unheld standard role, complete holder, hierarchy, permission, and discoverable dependency evidence, explicit irreversible-role-loss acknowledgement, signed review, and fresh absence plus survivor-preservation proof
• Guild pruning requires a separate exact guild allowlist, optional exact include-role allowlist, explicit acknowledgement that Discord does not reveal the candidate IDs, protected-identity role shields, a fresh native estimate below both requested and configured ceilings, signed review, and one non-retried request with strict count-only outcome evidence
• Guild incident actions require one exact allowlisted guild, complete known MANAGE_GUILD or owner evidence, future deadlines no more than 24 hours ahead, signed review, one non-retried sparse write, and exact response plus fresh readback; clearing protection early is treated as destructive
• Privileged-intent enablement accepts only Guild Members or Message Content when the strict policy proves that intent is required or recommended, preserves every observed non-target application flag, and excludes Presence, disabling, generic application editing, and automatic remediation

The common reviewed-write sequence is:

exact request -> fresh keyed plan -> human review -> signed approval
             -> final fresh-plan match -> pending content-free evidence
             -> one non-retried write -> exact readback or quarantine

Already-current requests are record-free no-ops where the Discord operation permits that proof. A known client rejection settles as failed. A transport failure, server failure, malformed success response, or missing readback is uncertain and must not be retried blindly. Durable claims keep the affected exact targets quarantined across connector processes until safe receipt evidence or explicit operator resolution proves what may proceed.

Read the complete safety model and security policy before enabling a write surface.

Trust and verification

catalog --check --json is designed for independent comparison. It needs no credential, ignores ambient connector authority, returns no completion identifiers, executes no Discord operation, opens no Gateway, exports no telemetry, and creates no activity record. Matching contract digests identify matching normalized MCP instructions, server capabilities, policy-completion bindings, tool schemas and annotations, prompt declarations, resource declarations, templates, safety response, plan-review app response, and execution guard.

The release workflow rebuilds candidates from source, packs them twice, installs them without lifecycle scripts, compares them across supported Node.js lines, builds an exact-version multi-architecture OCI image, tests the image under a read-only root filesystem with no capabilities or network, generates an SPDX SBOM, and retains signed provenance, SBOM, and catalog attestations. The release runbook documents the human-controlled publication gates and independent verification path.

Architecture

The stdio transport, Discord REST client, scope policy, domain services, reviewed planning, durable coordination, activity log, observability, Gateway, and MCP adapter remain separate. Production uses native fetch, TypeScript ESM, and a small exactly pinned dependency set.

This keeps transport, permission evidence, local authority, reviewed writes, persistence, and MCP presentation independently testable. New capabilities must fit those boundaries rather than add a generic Discord dispatcher.

Documentation

• Complete operator and capability reference
• Security model and reporting
• Release and independent verification runbook
• MCP Registry manifest
• AGPL-3.0-only license

Development

See CONTRIBUTING.md for changes and SUPPORT.md for setup and operator questions. Default tests use injected transports and do not contact Discord:

npm run metadata:check
npm run config:schema:check
npm run typecheck
npm test
npm run test:coverage
npm run build
npm run pack:verify
npm run container:verify
npm run container:index:verify
npm run security:check

Live probes are explicit and read-only by default. No default verification command fetches message content or performs a Discord mutation.

License

AGPL-3.0-only