Installation

discord-mcp ships as a single npm package (@discord-mcp/cli) that bundles the server.

Before you begin

• Open a terminal where you can install global Node.js packages.
• Keep the bot token private; this lesson does not require you to paste it into a command.

Requirements

• Node.js 22.12 or newer. This is the minimum declared by the published packages.
• A Discord bot installed in the test server with the permissions required by your calls.

Check your Node version with node --version. If you’re below 22.12, upgrade via fnm, nvm, volta, or your OS package manager.

Install with npm

npm install -g @discord-mcp/cli

Install with pnpm

pnpm add -g @discord-mcp/cli

Install with yarn

yarn global add @discord-mcp/cli

Verify the install

--version is a global flag, not a subcommand:

discord-mcp --version    # prints the package version and exits
discord-mcp --help       # prints the subcommand list

Caution

There is no version subcommand. serve is registered as commander’s default subcommand, so an unrecognized first argument falls through to it - discord-mcp version does not print anything, it boots a stdio MCP server that then sits waiting for JSON-RPC frames on stdin. Use --version.

Optional catalog check

Before configuring a Discord bot, validate the installed package’s real MCP catalog:

discord-mcp catalog --check
discord-mcp catalog --check --json

This command requires no Discord token and performs no Discord request or write. It is catalog validation only; it does not count as Activity Evidence. Continue to guided setup when you are ready to connect a caller-owned bot.

The JSON result uses schema discord-mcp.catalog-check.v1 and reports 209 tools, 6 static resources, a CATALOG_ONLY execution guard, discord_execution: "disabled", and activity_evidence_created: false. It validates the installed catalog contract; it does not prove AI-host connectivity or a live Discord connection.

discord-mcp --help lists ten subcommands:

Subcommand	What it does
serve	Start the local stdio MCP server. Default - a bare discord-mcp runs this. Use serve --http for a bearer-protected remote endpoint.
catalog	Expose all 209 real tool schemas without credentials or Discord access; execution always returns CATALOG_ONLY.
setup	Verify one caller-owned bot, save non-secret profile metadata, and generate its client config.
activity	Show the local, privacy-safe journal for setup, doctor, smoke, and blueprint lifecycle outcomes; --report prints the optional manual outcome-form URL.
update	Check a generated Codex launcher for a new release; --apply is always explicit.
profile	List, show, or remove local non-secret bot profiles.
doctor	Diagnose token/connectivity state and audit generated Codex, Antigravity CLI, Cursor Agent CLI, Grok Build CLI, or Gemini compatibility configuration with --client.
smoke	Verify the real MCP-to-Discord path; writes require the explicit --confirm-write flag.
init	Print an MCP client config snippet for Claude Desktop / Claude Code / Codex / Antigravity CLI / Cursor Agent CLI / Grok Build CLI / Gemini compatibility / Cursor editor / generic.
migrate	Map another Discord MCP server’s tools onto discord-mcp’s.

There is no start subcommand either - it is serve. See Reference → CLI for every flag.

Optional: Gateway mode

The default transport is REST-only - every tool call hits the Discord HTTP API. For real-time events (presence updates, voice state changes, typing, guild updates), discord-mcp can subscribe to the Gateway WebSocket via discord.js.

discord.js is not installed by default so REST users do not pay for it. It is lazy-imported, and it must be resolvable from the same install as the CLI - a separately global-installed package is not on another global package’s module resolution path. Install both together:

npm install -g @discord-mcp/cli discord.js
discord-mcp serve --gateway

When --gateway is set, the server lazy-imports discord.js and attempts to open a Gateway connection for live notification subscriptions. Gateway startup failure is non-fatal: the server logs a warning and continues in REST-only mode. Treat this surface as advanced; the the ordinary catalog remains static unless an allowlisted guild is configured; discord://guild/{id}/info is then listed/read as a short-lived live snapshot, while the other event URIs remain notification-only.

See Architecture → Gateway for the full integration model.

Checklist for moving on

• node --version reports Node.js 22.12 or newer.
• discord-mcp --version prints the installed package version and exits.
• discord-mcp --help lists serve, setup, activity, update, profile, doctor, smoke, init, and migrate.