discord-dm-mcp
Allows sending direct messages to Discord users via a bot, using Discord's REST API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@discord-dm-mcp Send a DM to user 123456789: 'Your PR is merged.'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
discord-dm-mcp
A tiny MCP server that lets Claude send Discord direct messages through a bot — with nothing to host.
Sending a DM is just two stateless HTTPS POSTs to Discord's REST API, so there is no
gateway/websocket connection to keep alive and no server to run. This package is a
stdio MCP server: it runs as a subprocess of whatever launches it — your local
Claude client, or a Claude cloud routine via a committed .mcp.json. Each user
brings their own Discord bot token; the package itself holds no secrets.
It exposes a single tool, send_discord_dm.
How "no hosting" works
Where you use it | Where the server runs | You host a machine? |
Local Claude Code / Desktop / Cursor | your laptop (a subprocess) | No |
Claude cloud routine (via | Anthropic's ephemeral sandbox | No |
The only path that would require hosting is a remote ("Connector chip") MCP server, because a remote MCP must be reachable at a URL. This package avoids that by using stdio. (See the trade-off.)
Related MCP server: Discord Bridge MCP Server
Prerequisites (one-time Discord setup)
Create a bot. https://discord.com/developers/applications → New Application → Bot → Reset Token → copy the token. This is your
DISCORD_BOT_TOKEN.You do not need any privileged intents (Message Content, etc.) — those gate the gateway, not REST sends. This bot never reads messages.
Invite the bot to your server with the
botscope and zero permissions (DMs aren't governed by a permission bit):https://discord.com/oauth2/authorize?client_id=YOUR_APP_ID&scope=bot&permissions=0The bot must share that server with every recipient. Discord only delivers a DM if the bot and the user have a mutual guild. Otherwise the send fails with error
50007("Cannot send messages to this user"). The recipient must also not have DMs disabled / the bot blocked.Get recipient user IDs. In Discord: Settings → Advanced → Developer Mode on, then right-click a user → Copy User ID. (Or build a consented GitHub→Discord mapping.)
Install — local Claude clients
No repo, no GitHub needed — just npm:
claude mcp add discord-dm \
--env DISCORD_BOT_TOKEN="your-bot-token" \
-- npx -y discord-dm-mcpFor Claude Desktop / Cursor, add the equivalent to the client's MCP config:
{
"mcpServers": {
"discord-dm": {
"command": "npx",
"args": ["-y", "discord-dm-mcp"],
"env": { "DISCORD_BOT_TOKEN": "your-bot-token" }
}
}
}Install — Claude cloud routine
A cloud routine can't use a local stdio server you added with claude mcp add
(that lives on your machine). Instead the routine clones a repo and reads
.mcp.json from it. So:
Point the routine at a repo that contains a
.mcp.json(the one at the root of this repo works as-is — itnpx-installs the published package):{ "mcpServers": { "discord-dm": { "command": "npx", "args": ["-y", "discord-dm-mcp"], "env": { "DISCORD_BOT_TOKEN": "${DISCORD_BOT_TOKEN}" } } } }The repo can be a near-empty stub — its only job is to carry this file. The
${DISCORD_BOT_TOKEN}is expanded from the routine's environment variable.Set the env var. In the routine's environment ("Default" or a custom one) add an Environment variable
DISCORD_BOT_TOKEN=....⚠️ Claude routines have no dedicated secrets store yet — env vars are visible to anyone who can edit the environment and may appear in transcripts. Treat this token as low-confidentiality and scope the bot to least privilege (it needs no guild permissions). Rotate it if a transcript is shared.
Allow Discord egress. The Default environment's "Trusted" network access blocks
discord.com(requests fail with403 host_not_allowed). Edit the environment's Network access to Full, or Custom withdiscord.comadded to the allowlist. (Custom-allowlist propagation has had bugs; if Discord still 403s, use Full.)Reference the tool from the routine Instructions, e.g. "If you're unsure whether to merge, call
send_discord_dmto ask the PR author."
Running from a checkout instead of npm (e.g. before publishing): copy
examples/.mcp.local-repo.json to the repo root as
.mcp.json and set the environment Setup script to npm ci && npm run build.
Tool: send_discord_dm
Field | Type | Notes |
| string | Recipient's numeric Discord ID. One of this or |
| string | Resolved to a Discord ID via |
| string | Plain message text, sent as-is. |
| object | Structured decision request (formatted into the body). Fields below. |
| string | Link to the PR / item. |
| string | What the agent is unsure about. |
| string | Relevant evidence / context. |
| string[] | Rendered as |
| string | The agent's recommended option. |
| boolean | Resolve + format but never call Discord. |
Provide content, escalation, or both. Mentions are always disabled
(allowed_mentions: { parse: [] }), so messages never accidentally ping @everyone,
roles, or users.
Errors are returned as tool errors (isError: true), not thrown: unknown recipient,
missing token, the no-mutual-guild 50007/50278 case (not retried), and other Discord
API failures. Rate-limit 429s are retried automatically honoring Retry-After.
Configuration (environment variables)
Var | Required | Purpose |
| to send | Bot token. Not needed for dry runs. |
| no |
|
| no | Inline JSON or path to a |
| no | Override |
Mapping GitHub logins to Discord IDs
Set DISCORD_USER_MAP to inline JSON ({"octocat":"123..."}) or a file path (see
examples/mapping.example.json). Keys match the GitHub
login case-insensitively. For a consented mapping, have users link their own GitHub
via Discord OAuth2 (identify + connections scopes) and only DM logins present in the
map.
Develop / verify
npm install
npm run build # tsc -> dist/
npm test # unit tests (pure functions)
npm run smoke # builds, starts the server over stdio, calls the tool in dry-runnpm run smoke proves the full MCP round-trip with no token and no network.
Why stdio and not a remote connector?
A custom connector (the chip in Claude's "Connectors" UI) is a remote MCP server: Claude connects out to a URL, so it must be hosted (even serverless = a deployment). A stdio server runs as a child process of the client, so it needs no host. The trade:
stdio (this package): no hosting; works locally and in cloud routines via
.mcp.json. Not shown as a Connector chip.remote connector: shown as a chip and reusable across clients, but you must host (serverless like Cloudflare Workers is the lightest option).
Responsible use
Discord's Developer Policy requires consent before initiating processes on a user's behalf and prohibits unsolicited / bulk DMs. Use this for opted-in, transactional, one-at-a-time notifications (e.g. asking a PR author a question), never to broadcast. Using a user token / selfbot to DM is forbidden by Discord and can get the account terminated — this package uses a proper bot token only.
License
MIT
Available Tools
1 toolsend_discord_dmSend Discord DMA
Send a direct message to a Discord user via a bot (REST only, no gateway). Provide either discordUserId or githubLogin (resolved via the configured mapping). Supply content for a plain message, and/or escalation to format a decision request. Mentions are always disabled (allowed_mentions.parse=[]). The bot must share a server with the recipient or Discord returns error 50007. Only DM users who have opted in — never mass-DM.
Inputs: dryRun, content, escalation, githubLogin, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 1 tool
Only one tool exists, so there is no ambiguity. An agent cannot confuse it with another tool.
The single tool name follows a clear verb_noun pattern (send_discord_dm), consistent with common MCP conventions.
A single tool for sending DMs is minimal but arguably appropriate if the server's sole purpose is to send DMs. However, it feels thin and could benefit from at least one more tool (e.g., to verify user availability).
The server only supports sending messages, lacking any way to check user opt-in status, retrieve conversation history, or handle errors like 50007. This leaves significant gaps for an agent.
Maintenance
Related MCP Connectors
Discord MCP server for ChatGPT, Claude and any AI agent: list servers and channels, read channel messages, search messages, send message, reply to message, send DM, read mentions and assign role in your own Discord account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Discord yourself; Cotlet does not store your password and you need no Discord API key. About the official Discord API: Yes, Discord has an official API for bots and OAuth2 apps, but it acts as a bot that a server manager adds, not as you, and Discord has no official MCP server for it (checked 5 Nov 2026). The MCP server on Discord's docs site only searches documentation. Setup and FAQ: https://cotlet.dev/integrations/discord-api-mcp-server
Hosted X (Twitter) MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Hosted YouTube MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Hosted Notion MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA simple MCP server that allows Claude to access your Telegram account to read and send messages on your behalf.7Apache 2.0
- AlicenseAqualityCmaintenanceAn MCP server that provides native Discord tools for Claude Code, enabling bidirectional communication with remote agents or humans via the Discord REST API. It allows users to send messages, read channel history, and manage reactions directly from their local environment.63MIT
- FlicenseNot gradedqualityDmaintenanceAn MCP server that enables Claude Desktop to interact with Discord through a dedicated bot. It allows users to list channels, read message history, and send messages directly from the AI interface.2-
- AlicenseNot gradedqualityFmaintenanceA simple MCP server that enables Claude to communicate with locally running LLM models via LM Studio.9MIT