Discord MCP for Codex

<img src="./assets/icon.png" alt="Discord MCP icon" width="128">

Discord MCP is a local Codex plugin that exposes a Discord bot as MCP tools. Codex starts the bridge when needed; no always-running gateway service or public server is required.

[!IMPORTANT] This project is not affiliated with or endorsed by Discord. Discord is a trademark of Discord Inc. Use the bot only in servers where you are authorized to administer it.

Requirements

• Codex desktop with local plugin support
• Node.js 18 or newer
• A Discord application with a bot user

What it can do

• Check bot connectivity and generate an invite URL
• List accessible servers, channels, and roles
• Create, edit, and delete channels
• Send messages
• Create, edit, and delete roles
• Add and remove member roles
• Call any guild-scoped Discord API v10 JSON endpoint through guarded read/write fallback tools

The fallback layer covers moderation, bans, timeouts, AutoMod, threads, reactions, emojis, stickers, scheduled events, onboarding, soundboard, permissions, bot-managed webhooks, and new guild-scoped REST endpoints without waiting for a plugin update.

Discord still enforces the bot's permissions, enabled intents, and role hierarchy. Destructive tools require a target-specific confirmation token. Every generic write is previewed and requires a request-bound confirmation token before execution.

Setup

1. In the Discord Developer Portal, create an application and add a bot.

2. Reset/copy the bot token. Never paste it into chat or save it in this plugin folder.

3. Run PowerShell and execute:

   & "$HOME\plugins\discord-mcp\scripts\configure.ps1"
   

   The script securely prompts for the token and optionally for a comma-separated guild ID allowlist. It stores the values in your Windows user environment so Codex can forward them to the MCP process.

4. Restart the Codex desktop app after configuration.

5. Install/enable Discord MCP from the Personal marketplace, then start a new task.

6. Ask: "Check my Discord bot status and give me its Administrator invite URL."

7. Open the Administrator invite URL and authorize the bot for the intended server. The status result also includes a least-privilege alternative.

To find a guild ID, enable Developer Mode in Discord, right-click the server icon, and choose Copy Server ID. Supplying DISCORD_ALLOWED_GUILD_IDS is strongly recommended; the bridge rejects every guild outside that list.

Install from source

1. Clone this repository into your local Codex plugins directory as discord-mcp.
2. Add the plugin to a local Codex marketplace or use the repository's plugin manifest with your existing local-plugin workflow.
3. Configure the bot credentials as described below.
4. Install or enable Discord MCP, restart Codex, and start a new task.

The plugin manifest is located at .codex-plugin/plugin.json, and the MCP server definition is in .mcp.json.

Release downloads

Every push to main that passes the test suite creates a GitHub Release with:

• A versioned discord-mcp-vX.Y.Z-build.N.zip plugin archive
• A matching SHA-256 checksum file
• Automatically generated release notes

The archive extracts into a discord-mcp directory and can be placed directly in a local Codex plugins directory. The semantic version comes from package.json; the GitHub Actions run number makes every main-branch build uniquely downloadable.

Configuration

• DISCORD_BOT_TOKEN (required): Discord bot token.
• DISCORD_ALLOWED_GUILD_IDS (recommended): comma-separated Discord guild IDs.

Run scripts/configure.ps1 -Clear to remove both user environment variables.

On macOS or Linux, set the same variables in the environment used to launch Codex. For example:

export DISCORD_BOT_TOKEN='your-token'
export DISCORD_ALLOWED_GUILD_IDS='123456789012345678'

Do not put real values in a tracked file or paste them into a Codex task.

Administrator access

discord_status now returns:

• administrator_invite_url, which requests Discord's ADMINISTRATOR permission bit (8)
• least_privilege_invite_url, which requests only the plugin's common management permissions
• invite_url, which points to the Administrator invite for convenience

For a bot already in the server, reauthorize it with administrator_invite_url or enable Administrator on its bot role in Server Settings → Roles. Move the bot role above every role it needs to manage. Administrator bypasses channel permission overwrites, but it does not bypass role hierarchy and cannot act on the server owner.

Architecture

Codex communicates with a dependency-free local Node.js MCP server over stdio. The MCP server calls Discord API v10 over HTTPS using the bot token. It does not listen on a network port, receive Discord messages, or require privileged gateway intents.

Coverage and limits

The guarded fallback tools support guild-scoped JSON REST endpoints using GET, POST, PUT, PATCH, and DELETE. They resolve guild ownership from guild, channel, stage, invite, or bot-authenticated webhook routes before making a request.

This on-demand local bridge does not implement Discord Gateway event listeners, persistent presence, voice/audio streaming, interaction callbacks that require temporary tokens, OAuth user flows, webhook-token execution routes, or multipart file uploads. Those features require a separate continuously running bot runtime or a purpose-built upload flow. Credential-bearing routes and JSON fields are deliberately blocked.

Security notes

• Administrator is extremely powerful. Use it only in servers you control, keep the guild allowlist enabled, and protect the bot token like a password.
• Keep the allowlist enabled.
• Discord audit-log reasons are sent for supported administrative changes.
• Raw writes are bound to their method, path, query, body, and audit reason; changing any of them invalidates the confirmation token.
• Credential-like fields are blocked in request bodies and recursively redacted from raw API responses.
• Rotate the bot token immediately in the Developer Portal if it is ever exposed.

See SECURITY.md for private vulnerability-reporting guidance.

Development

The MCP server has no runtime package dependencies. Run the local checks and protocol smoke test with:

npm test

The smoke test uses a placeholder token and does not call Discord. Pull requests are also checked by GitHub Actions. See CONTRIBUTING.md for contribution guidelines and CHANGELOG.md for release history.

License

The source code is available under the MIT License. Third-party names, logos, and trademarks remain the property of their respective owners.