A live bridge between a Claude Code agent and a running Discord (Vencord) client. The agent can interact with Discord — list DMs by name, open a channel, read the messages you are currently looking at, and send a message (with a pretend-typing indicator, attachments, reply refs) — and inspect its runtime (webpack modules, the DOM, minified class names) instead of guessing.
The bridge is split so the MCP tools always connect, no matter how many Claude Code sessions are open:
daemon.ts— owns127.0.0.1:8788and the long-poll connection to the Vencord plugin. Long-lived and a singleton: only one process can bind the port; a second daemon loses the race and exits. Started detached (setsid) so it survives the Claude Code session that spawned it — and a Discord reload, since the daemon runs outside the renderer.server.ts— the per-session MCP stdio server. Claude Code spawns one per session. It owns no port; every tool call is proxied over HTTP to the daemon. On startup it ensures the daemon is up, spawning it if not.discordMcp/— the Vencord userplugin half. Runs in the Discord renderer and long-polls the daemon, evaluating the code the agent sends.
The renderer cannot listen for connections, so it connects out. Discord's CSP
blocks ws://localhost (a schemeless/http connect-src source does not
permit an insecure ws:// from an https page) but allows
http://localhost — so the transport is HTTP long-polling. The daemon also
sends Access-Control-Allow-Origin so the cross-origin fetch is readable.
Needs Bun, Claude Code, and a Vencord source build.
git clone https://github.com/fagnersales/discord-mcp-bridge.git
cd discord-mcp-bridge
./install.sh ~/Vencord # bun install + copy discordMcp into VencordThe installer copies the plugin instead of symlinking it. Vencord's esbuild
build follows symlinks to their real path; if the plugin source appears outside
the Vencord tree, aliases like @api/Settings and @webpack fail to resolve.
After editing files in discordMcp/, run ./install.sh ~/Vencord again before
rebuilding Vencord.
If you use Vesktop and have other folders under src/userplugins, build with:
./build-vencord-discordmcp-only.sh ~/VencordVencord builds every userplugin it finds. This helper temporarily moves other userplugins aside, builds the dist with only DiscordMCP, then restores them in the source tree.
Then register the MCP server with Claude Code (user scope) and restart it:
claude mcp add discord-bridge -s user -- "$(which bun)" "$PWD/server.ts"Build & deploy Vencord, enable the DiscordMCP plugin in Vencord settings,
press Ctrl+R — discord_status should then report the plugin connected.
For Vesktop on macOS, "deploy" means copying the built dist into the dir Vesktop actually loads Vencord from, then reloading:
cp ~/Vencord/dist/* "$HOME/Library/Application Support/vesktop/sessionData/vencordFiles/"Keep Vencord's autoUpdate setting OFF (settings/settings.json →
"autoUpdate": false). With it on, any new upstream Vencord release gets
downloaded over vencordFiles/ on reload, silently removing this plugin —
the bridge then reports "plugin DISCONNECTED" until you re-copy the dist.
If discord_reload can't reach a renderer whose plugin is already gone,
restart Vesktop itself (osascript -e 'quit app "vesktop"' && open -a vesktop).
discord_dms({query?, limit?})— list DMs and group DMs in sidebar order. Withquery, ranks matches by exact > prefix > substring across the DM display name, recipient global / username, and the Discord friend-nickname the sidebar actually shows (viaRelationshipStore.getNickname) — so a query for "Dragãozinha" resolves even when the underlying account is "pitucoco".discord_open({channelId, messageId?})— switch Discord to a channel (DM / group / guild). Same code path as the sidebar (ChannelActions.selectChannel); optionalmessageIdscroll-jumps to that message. Confirms the selection actually flipped.discord_view({limit?, includeEmbeds?, includeReactions?})— read what the user is currently looking at: the selected channel + the messages rendered in the viewport. Discord virtualizes off-screen messages out of the DOM, so this is naturally scroll-scoped — if the user scrolled up to look at history, that slice is what comes back. Each message includes author info, content, timestamp, attachments, reply ref, mentions;scroll.atBottomtells you if the user is following live or browsing history.discord_send({content?, channelId?, replyToMessageId?, files?, tts?, typing?, typingMs?})— send a message natively viaMessageActions.sendMessage(orUploadManager.uploadFileswhen files are attached). Same code path as Discord's composer, so it is not blocked byisTrusted=falsethe waydiscord_clickis.channelIddefaults to the currently selected channel. Settyping: trueto show the typing indicator first (duration auto-derived from content length, ~60ms/char clamped to 800–6000 ms) ortypingMs: Nfor an explicit duration — feels less robotic than instant sends.discord_guilds()— read the left-sidebar layout: top-level guilds and folders in display order. Each entry is{kind:"guild", guildId, name}or{kind:"folder", id, name, color, expanded, guildIds, guilds:[{id,name}]}.coloris a 24-bit RGB integer (the Discord folder swatch). A separateorphansarray lists guilds the user is in but not referenced by any entry (Discord parks newly-joined guilds there).discord_waitForMessage({channelId?, fromUserId?, contains?, mentionsViewer?, includeSelf?, maxMatches?, timeoutMs?})— block until a new Discord message arrives that matches the filter (or untiltimeoutMselapses, default 60 s, max 10 min). Subscribes inside the renderer to FluxDispatcherMESSAGE_CREATE— event-driven, no history polling. Catches messages in DMs, group DMs, and guild channels alike. Filters AND together; omit a filter to match anything in that dimension. Triggers on phrases like "wait for a message", "wait for his/her response", "respond when X messages me", "let me know when someone writes in this group". Default skips the viewer's own outgoing messages (includeSelf: trueto include server-confirmed self-sends). Returns{done, timedOut, matches: [{id, channelId, content, timestamp, author, …}]}.discord_organize({sidebar, apply?})— rewrite the sidebar layout: reorder, group into folders, rename / recolor folders, ungroup, move guilds between folders.sidebaris the full ordered list of top-level entries; every guild inGuildStoremust appear exactly once across all entries. Entry forms:{kind:"guild", guildId}(top-level) or{kind:"folder", guildIds:[...], name?, color?, id?}(folder). Pass an existing folder'sidfromdiscord_guildsto preserve expand/collapse state; omit it to auto-mint. Default is dry-run — returns the resolved preview without writing. Passapply: trueto commit via Discord's user settings proto (syncs to the user's other Discord clients). The tool rejects unknown guildIds — strip "ghost" entries (left guilds still in proto) before retrying; append new joins (orphans) explicitly so they aren't dropped.discord_join({invite, apply?})— join a server from an invite (full URL or bare code). Default is dry-run — resolves the invite and returns the target guild / channel / inviter / member counts without joining. Passapply: trueto join. Idempotent (alreadyMember: trueif already in). The returnedjoinedboolean reflects the live guild store, not a guess. Large/flagged servers gate joins behind a captcha the bridge can't solve (cross-origin anti-bot iframe) — see Captcha below.discord_onboarding({answerOptional?, allServers?, maxQuestions?})— auto-complete the "Question X of Y" onboarding questionnaire shown right after joining a community server. Required questions get their first option selected then Next; optional questions are Skipped (answerOptional: trueto answer them too). Scoped to the current server unlessallServers: true(Discord chains several freshly-joined servers' onboarding back-to-back). Safe no-op (reports it) when no onboarding screen is up. Returns a per-question log.discord_leave({guildId, apply?})— leave a server by guild ID. Destructive. Default is dry-run — verifies membership and returns the resolved guild without leaving. Passapply: trueto actually leave; the returnedleftboolean reflects the live guild store (re-checked after the leave), not a guess.
discord_config({captchaCommand?, captchaTimeoutMs?, clearCaptcha?})— read (no args) or update the config file at~/.config/discord-mcp-bridge/config.json. Currently holds the captcha solver hook.
When discord_join({apply:true}) hits a captcha, the bridge itself does not
click anything — it has no mouse/screen code and is OS-agnostic. Instead:
- It detects the captcha and returns
captchaRequired: true. - If a
captchaCommandis configured, it shells out to that command, waits, then re-reads the guild store and reports the realjoined. - With no command configured, it returns setup instructions — a human can
solve the captcha in the Discord window, then re-run
discord_jointo confirm.
The command is user-supplied and platform-specific — it must locate and
solve the on-screen captcha itself (it gets CAPTCHA_GUILD_ID /
CAPTCHA_GUILD_NAME / CAPTCHA_INVITE in env + the same JSON on stdin, but
no pixel coordinates — those would break across resolutions / window
positions). Exit 0 once solved. A reference Windows solver (Interception-driver
mouse + RapidOCR checkbox locate) lives in
examples/solve-captcha.windows.ts.
Note: auto-solving a captcha defeats Discord's anti-bot control — it is
inherently unreliable (works on a low-risk session, refused once flagged) and
carries account risk. The bridge falls back to a human cleanly rather than
faking success.
discord_eval({code?, file?, depth?})— eval JS in the renderer (expression or statements +return).fileevals a local.jsfile;depth(1–20, default 8) sets result serialization depth.discord_query(selector, limit?)— querySelectorAll; returns tags/classes/HTML.discord_findModule({code?, props?})— search webpack modules (source / exports).discord_screenshot({selector?, format?, maxWidth?, quality?})— capture the renderer as an image (whole window, or one element); returns it inline so the agent can see the UI.discord_console(limit?)— recent renderer warnings / errors / uncaught.discord_click(selector, index?)— synthetic pointer/mouse/click on an element.discord_key(combo, selector?)— dispatch a key / shortcut, e.g."Ctrl+K".discord_wait({selector?, expr?, timeoutMs?})— block until a selector appears or a JS boolean expression is truthy.discord_reload()— reload the renderer and wait until the bridge reconnects.discord_status()— daemon up? plugin connected? + renderer liveness snapshot.
discord_notes({action, key?, value?, topic?, userId?, channelId?})— a tiny persistent notebook so the agent can remember things about you across sessions: writing style, recurring contacts, group conventions, preferences. Actions aresave/recall/forget. Each note can be tagged with auserIdand/orchannelId, anchoring it to a specific person / DM / channel — and many notes can share the same id.recallwith no filter dumps every saved note grouped by topic (good at session start);recallwith auserId/channelId/topicfilter returns just the matching slice, so after resolving "main group" to a channelId the agent can pull only the notes about that group. Stored locally asnotes.jsonnext to the bridge; nothing leaves the machine.
discord_dms({ query: "kavi" }) → grab the 1:1 channelId
discord_open({ channelId }) → switch Discord to it
discord_view({ limit: 30 }) → read recent messages for context
discord_send({ → reply, with a natural typing pause
channelId, content: "...",
replyToMessageId: "...",
typing: true,
})
discord_dms({ query: "kavi" }) → resolve channelId + userId
discord_waitForMessage({ → blocks until Kavi sends a message
channelId, fromUserId,
timeoutMs: 300_000, // 5 min
})
→ { matches: [{ id, content, … }] }
discord_send({ → reply to that specific message
channelId,
replyToMessageId: matches[0].id,
content: "...",
})
-
POST /poll— plugin long-polls (held ≤25s) →{id, code, depth}. -
POST /result— plugin posts{id, ok, result|error}. -
POST /eval?depth=N— round-trip raw JS; the smoke-test path:curl -s -X POST 'http://localhost:8788/eval?token=vc-debug-bridge-2f9a4c1e' --data-binary 'document.title' -
POST /screenshot— body{selector?, ...}; captures the renderer, returns{ok, result:{data, mimeType, width, height, bytes}}(datais base64). -
GET /health— daemon liveness (no plugin needed). -
GET /status— daemon + plugin + renderer snapshot. -
POST /reload— reload Discord, wait for reconnect. -
POST /shutdown— stop the daemon.
- Token:
vc-debug-bridge-2f9a4c1eis a localhost-only shared secret — it only stops other local pages from hitting the endpoint. To change it, edit theTOKENconstant indaemon.ts,server.ts, anddiscordMcp/index.tsx. - The plugin polls
http://localhost, falling back tohttp://127.0.0.1. - Daemon logs to
daemon.login this directory. - Screenshots use a native helper (
discordMcp/native.ts,webContents.capturePage()). Native handlers register only at Discord startup — after first installing this, fully quit and reopen Discord once;Ctrl+Ris not enough. After that,Ctrl+Rworks as before. - Security: while enabled the plugin evals arbitrary JS inside Discord. Localhost-only + token. Keep it disabled when not actively debugging.
GPL-3.0-or-later (the discordMcp plugin matches Vencord's license).