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.

discord-mcp --help lists four subcommands:

Subcommand	What it does
serve	Start the stdio MCP server. Default - a bare discord-mcp runs this.
doctor	Diagnose config, token shape, and (with --online) connectivity.
init	Print an MCP client config snippet for Claude Desktop / Claude Code / Cursor / 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 ordinary MCP resource catalog remains the static Components V2 catalog and does not expose those live URIs through resources/list or resources/read.

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, doctor, init, and migrate.