codex-discord-mcp
Provides tools for interacting with Discord, enabling AI agents to send messages, read message history, add reactions, edit messages, download attachments, and manage a local queue of Discord messages for processing.
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., "@codex-discord-mcp fetch the last 10 messages from #general"
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.
codex-discord-mcp
A local-first Discord bridge for Codex CLI.
Use it in three ways:
Discord -> Codex: mention or DM your bot, run
codex exec --json, and post the final answer back to Discord.Codex -> Discord: expose Discord tools to Codex through MCP, including
reply,fetch_messages,react,edit_message,download_attachment,latest_generated_images, andrecover_generated_image.Hybrid workflow: receive Discord messages into a local queue, then let Codex inspect and respond through MCP tools.
This is not an official OpenAI plugin. It is a local bridge designed around Codex CLI, MCP, and Discord bot APIs.
Which Mode Should I Use?
Goal | Use |
DM Codex from Discord |
|
Let Codex send Discord replies |
|
Let Codex read recent Discord messages |
|
Queue Discord messages for Codex to inspect |
|
Fully automatic Discord -> Codex -> Discord |
|
Related MCP server: codex-from-chatgpt
Security Model
This bridge treats Discord as untrusted input.
Discord users cannot:
approve pairings
allow users
allow channels
change bridge policy
read bridge state files
bypass Codex sandbox or approval settings
Only local terminal commands can change access policy. MCP tools can read and reply through allowlisted Discord channels, but they cannot modify the allowlist or approve pairings.
Default safety posture:
Default sandbox:
read-onlyDefault approval policy:
never, becausebotmode is non-interactiveRecommended first run:
read-onlyUse
workspace-writeonly in an isolated repository or disposable worktreeNever use
danger-full-accessfor a public Discord channel
When bot mode starts with CODEX_SANDBOX=workspace-write or CODEX_SANDBOX=danger-full-access and CODEX_APPROVAL_POLICY=never, the bridge prints a runtime warning. Set CODEX_DISCORD_ASSUME_YES=true to suppress the warning in controlled automation.
Requirements
Node.js 20 or newer.
Codex CLI installed and authenticated for
botmode.A Discord application with a bot token.
Discord bot privileged Message Content Intent enabled.
Install
Global install:
npm install -g codex-discord-mcp
codex-discord-mcp doctor
codex-discord-mcp initRun through npx without a global install:
npx -y codex-discord-mcp doctorLocal development install:
npm install
npm run build
node ./dist/cli.js --helpDiscord Bot Setup
Create a Discord application in the Discord Developer Portal.
Add a bot and copy its token.
Enable Message Content Intent for the bot.
Invite the bot to a server if you want guild channels.
Useful bot permissions:
View Channels
Send Messages
Send Messages in Threads
Read Message History
Attach Files
Add Reactions
Print an invite URL:
codex-discord-mcp invite-url <client-id>Store the token locally:
codex-discord-mcp configureThe token is written to ~/.codex/discord/.env by default. Override the state directory with CODEX_DISCORD_STATE_DIR.
You can also read the token from an existing environment variable:
codex-discord-mcp configure --token-env DISCORD_BOT_TOKENQuick Start
Interactive setup:
codex-discord-mcp initCheck local configuration:
codex-discord-mcp doctor
codex-discord-mcp doctor --jsonMode 1: Discord To Codex Relay
Run:
codex-discord-mcp botDefault behavior:
Unknown DM users receive a one-hour pairing code.
Pair locally with
codex-discord-mcp access pair <code>.After pairing, each DM message triggers
codex exec --json.The final Codex message is posted as a Discord reply.
Files the run produced are attached to that reply automatically (see below).
Useful environment variables:
export CODEX_WORKDIR="/path/to/repo"
export CODEX_SANDBOX="read-only"
export CODEX_APPROVAL_POLICY="never"
export CODEX_RESUME_BY_CHANNEL="true"
codex-discord-mcp botFor unattended relay mode, keep CODEX_APPROVAL_POLICY=never and use the least permissive sandbox that fits the channel.
Relay File Delivery
bot mode delivers files, not just text, on by default (CODEX_DISCORD_RELAY_ATTACHMENTS=false disables both paths):
Generated images. Codex's built-in
image_genusually writes no file to disk; the image survives only as base64 inside the session rollout. The relay records the rollout size before each run and, after the run, decodes anyimage_generation_callresults appended past that offset — so it attaches exactly the images this run generated, even on long resumed threads, without re-reading the whole rollout.Outbox deliverables. The prompt tells Codex to save user-facing files under a per-channel outbox directory (
CODEX_DISCORD_OUTBOX_DIR, default~/.codex/discord_outbox/<channel-id>/). Document, data, archive, and media files written there during the run are attached to the reply; code files, logs, and dotfiles are ignored.
Attachments respect Discord limits: at most 10 files per reply, 25MB each. If attaching fails, the relay retries text-only so the answer itself is never lost.
Files the user attaches to a Discord message are downloaded into the bridge inbox before the run (CODEX_DISCORD_RELAY_DOWNLOAD_ATTACHMENTS=false disables this), and the prompt lists each one's local path so Codex can read it directly. Inbox files older than 7 days are pruned.
Relay Commands
Send one of these as the whole message (in mention-gated channels, @bot !status works too). They are answered immediately, even while a long run is busy:
Command | Effect |
| What is running, for how long, how many messages are queued, and which thread the channel resumes |
| Cancel the running Codex task (SIGTERM, then SIGKILL) and drop queued messages |
| Forget the channel's resumed thread so the next message starts a fresh conversation ( |
| List the commands |
/status, /stop, /new, /help, and the aliases !cancel / !reset work the same way. Runs in one channel are serial; a message that arrives while a run is busy gets a ⏳ reaction until its turn starts.
Restarts
On shutdown the relay cancels in-flight runs instead of orphaning them, and leaves those messages pending. On the next start, pending messages received within CODEX_DISCORD_REPLAY_MAX_AGE_MS (default one hour) are replayed; older ones are marked handled and skipped, so a crash never re-runs a stale request hours later.
While a relay is running, mcp mode servers sharing the same state directory (the interactive Codex, or the one Codex starts inside each relay run) leave inbound handling to the relay: they keep serving outbound tools but stop duplicating typing indicators, ack reactions, pairing replies, and queue writes.
Mode 2: Codex MCP Tools
Print a local config snippet:
codex-discord-mcp print-configPrint an npx based config snippet:
codex-discord-mcp print-config --npxAdd the snippet to ~/.codex/config.toml or a trusted project .codex/config.toml. A typical npx config looks like:
[mcp_servers.discord]
command = "npx"
args = ["-y", "codex-discord-mcp", "mcp"]
startup_timeout_sec = 20
tool_timeout_sec = 60Then start Codex and run /mcp to confirm the Discord tools are loaded.
Available MCP tools:
Tool | Risk | Notes |
| Low | Reads recent allowlisted channel history |
| Low | Reads local queue entries |
| Low | Reads local bridge status |
| Low | Adds a reaction |
| Medium | Sends a Discord message |
| Medium | Sends a Discord message |
| Medium | Edits a message previously sent by the bot |
| Medium | Downloads Discord attachments into the local inbox |
| Low | Returns absolute paths of the newest images from Codex's |
| Medium | Decodes the most recent |
| Medium | Mutates local queue state |
Access Control
Access is managed by local CLI commands, not MCP tools.
codex-discord-mcp access show
codex-discord-mcp access policy allowlist
codex-discord-mcp access allow-user 123456789012345678
codex-discord-mcp access allow-channel 234567890123456789
codex-discord-mcp access allow-channel 234567890123456789 --no-mentionDM policy values:
pairing: unknown DM users get a one-hour pairing code. This is the default.allowlist: unknown DM users are silently ignored.disabled: all DMs are ignored.
Guild channels are opt-in by channel ID. By default, the bot only responds in an allowed guild channel when it is mentioned or when the user replies to a recent bot message. Use --no-mention only for dedicated bot channels.
Attachment Safety
The bridge refuses to attach its own state files, except files downloaded into the inbox. It also blocks attachment paths outside the configured attachment roots.
Attachment uploads are restricted by default to:
the bridge process working directory
CODEX_WORKDIRthe bridge inbox
Codex's built-in
image_genoutput directory (~/.codex/generated_images, orCODEX_DISCORD_GENERATED_IMAGES_DIR)the relay outbox (
~/.codex/discord_outbox, orCODEX_DISCORD_OUTBOX_DIR)
The image_gen output directory is always allowed so generated images can be
attached. Codex's built-in image_gen shows an inline preview but often writes
no file to disk — in that case call recover_generated_image, which decodes the
just-generated image from the active session rollout and saves it to the
image_gen output dir, returning the absolute path. (latest_generated_images
lists already-saved image files.) Then pass the path in the files array of
reply/send_message.
To allow generated files from other roots, set CODEX_DISCORD_ATTACHMENT_ROOTS using your platform path delimiter:
export CODEX_DISCORD_ATTACHMENT_ROOTS="/path/to/repo:/path/to/exports"On Windows PowerShell:
$env:CODEX_DISCORD_ATTACHMENT_ROOTS="C:\path\to\repo;C:\path\to\exports"Configuration Reference
Variable | Default | Meaning |
| required | Discord bot token |
|
| Bridge state directory |
|
| Codex executable |
| process cwd | Working directory for Codex |
|
| Codex sandbox mode |
|
| Codex approval policy for non-interactive bot mode |
| unset | Override Codex model |
| unset | Use a Codex profile |
|
| Resume one Codex thread per Discord channel |
|
| Codex process timeout in milliseconds |
| unset | Extra arguments passed to Codex |
|
| Pass |
| cwd, workdir, inbox | Allowed outbound file roots |
|
| Codex |
|
|
|
|
| Base directory Codex is told to save relay deliverables under (one subdirectory per channel) |
|
|
|
|
|
|
|
| Suppress writable unattended bot warning |
Troubleshooting
codex-discord-mcp doctor
codex-discord-mcp access showIf the bot receives empty message content, enable Message Content Intent in the Discord Developer Portal.
If bot mode cannot launch Codex, set CODEX_COMMAND to the full executable path or run the bridge from the same shell where codex exec "hello" works.
If MCP tools do not appear, run:
codex-discord-mcp print-config --npxThen add the printed snippet to Codex config and restart Codex.
Development
npm install
npm run typecheck
npm test
npm run buildDevelopment commands:
npm run dev:mcp
npm run dev:botRelease
GitHub Releases publish to npm through .github/workflows/release.yml.
Make sure npm trusted publishing is configured for
Openclaw-Metis/codex-discord-mcpand therelease.ymlworkflow.Bump
package.jsonandpackage-lock.jsonto the release version and commit the change.Create a GitHub Release whose tag is
vplus the package version, for examplev0.3.0.
The release workflow checks that the tag matches package.json, runs typecheck, tests, and build, then publishes to npm with provenance. Normal releases use the npm latest dist-tag; GitHub pre-releases use next.
The package itself ships the codex-discord-mcp bin, a files whitelist, and a prepublishOnly gate (typecheck, tests, build).
Available Tools
11 toolsbridge_statusA
Show bridge state path, queue counts, and Discord login status.
Inputs: no named parameters.
download_attachmentA
Download all attachments from a Discord message into the local bridge inbox and return absolute paths.
Inputs: chat_id (required), message_id (required).
edit_messageA
Edit a Discord message previously sent by the bot.
Inputs: text (required), chat_id (required), message_id (required).
fetch_messagesB
Fetch recent Discord channel history, oldest first. Discord's bot API does not expose full search.
Inputs: channel (required), limit.
latest_generated_imagesA
Return absolute paths of the most recently generated images from Codex's built-in image_gen output directory (default ~/.codex/generated_images), newest first. Use this to recover the path of an image you just generated so you can attach it via the files array of reply or send_message.
Inputs: limit.
list_pending_messagesA
List queued inbound Discord messages that have not been marked handled. Use this because Codex MCP has no Discord push channel.
Inputs: limit.
mark_message_handledA
Mark a queued Discord message as handled after replying or deciding no reply is needed.
Inputs: queue_id (required).
reactA
Add an emoji reaction to a Discord message. Unicode emoji work directly; custom emoji use Discord custom emoji syntax.
Inputs: emoji (required), chat_id (required), message_id (required).
recover_generated_imageA
Recover the most recently generated image(s) from the active Codex session rollout and write them to disk. Codex's built-in image_gen shows an inline preview but usually writes no file; this decodes the image from the session log and saves it to the generated-images dir, returning absolute path(s) ready to pass to the files array of reply/send_message. Optional count (default 1) and session_file (absolute rollout path; defaults to the newest session).
Inputs: count, session_file.
replyA
Reply in Discord. Pass chat_id from a queued message. Optional reply_to threads under a Discord message id. Optional files are absolute local paths.
Inputs: text (required), chat_id (required), files, reply_to.
send_messageA
Send a Discord message to an allowlisted chat. Same behavior as reply, but the name is explicit for non-reply sends.
Inputs: text (required), chat_id (required), files, reply_to.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
reply and send_message are described as identical in behavior, causing clear overlap and potential misselection. latest_generated_images and recover_generated_image also serve similar purposes with subtle differences that could confuse. Other tools are distinct enough.
Naming mixes verb_noun patterns (send_message, edit_message) with bare verbs (reply, react) and noun phrases (latest_generated_images, bridge_status). While most names are readable, the inconsistency undermines predictability.
At 11 tools, the count is reasonable for a Discord integration, though a few tools (reply/send_message) appear redundant and could be consolidated. Not excessive or thin.
Core Discord operations (send, edit, react, fetch, attachments) are covered, along with a queue mechanism and status check. Missing delete message and channel listing are minor gaps; agents can work around them using existing tools.
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
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
No-data MCP handoff for local Claude Code to Codex harness moves. $49 lifetime.
A paid remote MCP for OpenAI Codex agent coordination MCP, built to return verdicts, receipts, usage
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceCodex Bridge MCP is a local MCP orchestration service for a stable Claude Code x Codex CLI development workflow.2-
- AlicenseNot gradedqualityCmaintenanceA personal MCP bridge that lets ChatGPT drive a local Codex CLI, translating instructions into Codex app-server threads and returning compact summaries of what Codex did.16MIT
- AlicenseNot gradedqualityBmaintenanceA local stdio MCP server that lets any MCP client start a Codex thread and continue it by opaque thread ID through the codex and codex-reply tools, with fail-closed sandboxing and approval policies. It restores the removed Codex CLI MCP integration by bridging clients like OpenCode to the official Codex SDK.MIT
- AlicenseAqualityCmaintenanceA local MCP bridge that connects existing Codex and Claude Code conversations with DSH Web, enabling delegation, result retrieval, and human-in-the-loop coordination without leaving native chat apps.111MIT