vibhanshu-mishra/discord-mcp-server

---

Project overview

Discord MCP Server supports full Discord read/write operations and local analytics. The packaged Claude Desktop extension enables the registered Discord tools by default, while an optional source-level read-only mode remains available for restricted deployments.

• Write-enabled desktop extension. The packaged extension starts with DISCORD_READ_ONLY=false; messages, threads, channels, roles, member moderation, permissions, webhooks, invites, scheduled events, forums, bot DMs, and analytics tools are available immediately.
• Optional source-level read-only mode. Developers and restricted deployments can still set DISCORD_READ_ONLY=true, which hides and blocks Discord mutations while allowing local analytics operations.
• Private local SQLite analytics. Messages, reactions, threads, and voice sessions are stored in a database on your own machine.
• Deterministic metrics. Member engagement, per-user activity, staff response health, unanswered/unacknowledged candidates, training cadence, office-hour attendance, and weekly reports are all reproducible, no black box.
• Privacy-controlled qualitative analysis. Lexical topic candidates, recurring-question groups, feedback signals, conversation context, and evidence packets. Message content output is off by default, and the server calls no external AI provider, your MCP client does any interpretation.
• Operations CLI. Diagnose (doctor), check the database, sync history, back up, export, and prune from the terminal, no MCP client required.
• Claude Desktop extension. Package everything as a single .mcpb for one-click local installation (recommended for non-developers).

---

Recommended installation — Claude Desktop extension (no coding)

The easiest way to use Discord MCP Server is the one-click desktop extension. You do not need to clone this repository, install Node.js, run npm, or edit any JSON.

1. Download Discord-MCP-Server-2.2.1.mcpb from the project’s GitHub Releases page.
2. Open Claude Desktop.
3. Go to Settings → Extensions → Advanced settings.
4. Select Install Extension.
5. Choose the downloaded .mcpb file.
6. Complete the configuration form:
   • Discord bot token (from the Discord Developer Portal).
   • Discord server (guild) ID (enable Developer Mode in Discord → right-click the server → Copy Server ID).
   • Local data directory (a private folder outside the extension; a per-user default is suggested).
   • Optional: primary user ID, staff user IDs, resource/office-hour channel IDs, history start date, time zone, and privacy toggles.
7. If the tools do not appear, restart Claude Desktop.
8. Open the connector/tools menu to confirm the Discord tools are listed.
9. Ask Claude to synchronise Discord (see examples below).
10. Ask Claude for metrics.

Claude Desktop starts the local server automatically when a conversation needs it and stops it when it is no longer needed. See docs/desktop-extension.md for building, upgrading, uninstalling, logs, and troubleshooting.

Example Claude requests

• “Sync Discord activity since last Monday.”
• “Generate the most recently completed weekly metrics report.”
• “Show unanswered questions older than 24 hours.”
• “Show member engagement for the current month.”
• “Check whether training was posted in every configured resource channel.”
• “Analyse recurring question candidates.”
• “Produce a privacy-safe qualitative analysis packet.”
• “Send a message in the announcements channel saying the workshop starts in 10 minutes.”
• “Reply to the latest question in the support channel.”
• “Add a reaction to this message.”
• “Create a new role for moderators.”
• “Show me what would happen if I run this destructive action before executing it.”

---

Capabilities

• Historical message sync — import past messages from readable text channels, announcements, forum posts, and (where permitted) threads, on demand for any date range. Re-running is idempotent.
• Live collection (while running only) — new messages, edits, deletions, reactions, thread changes, and voice-state changes are collected only while the server process is running (i.e. while Claude Desktop is invoking it). Gaps outside that window are filled by historical message sync, except voice, which is prospective only.
• Stored data — messages, reactions, threads, and voice sessions (metadata; attachment metadata only, never downloaded files).
• Member engagement — messages, active days, distinct channels, replies sent/received, unique reply partners, reactions received, and candidate questions per member.
• Selected-user activity — the same activity for any supplied user ID (generic; not tied to any named person).
• Staff response health — response rate, within-window rate, and average/median/p90 first-response times.
• Unanswered-question candidates and unacknowledged-message candidates heuristic lists for human review.
• Training cadence — which resource channel-weeks contain a probable training/resource post.
• Office-hour metrics — voice attendance (unique/first-time/repeat, durations, incomplete sessions), prospective only.
• Weekly metrics — a single structured report combining the above with previous-week comparisons and an optional primary-user section.
• Topic candidates, recurring-question candidates, and feedback signals deterministic lexical candidates (not semantic, not AI).
• Conversation context — bounded local context around a message (before/after, replies, thread).
• Privacy-safe evidence packets — deterministic evidence for a client to summarise (the server never writes prose).
• Backups, exports, and pruning — via the operations CLI.
• Discord writes by default in the packaged extension — send, reply to, edit, delete, pin, crosspost, forward, and react to messages; manage threads, channels, roles, member permissions and moderation; manage webhooks, invites, scheduled events, forums, and supported bot DMs.

---

Safety and privacy

• The packaged extension enables Discord writes by default. Its fixed DISCORD_READ_ONLY=false setting exposes all registered write tools without an extra configuration step. Source-level deployments still default to read-only when the variable is missing or invalid and can deliberately set it to true.
• MCP permission does not override Discord permission. Write mode only permits the MCP server to attempt an action. Discord still enforces the bot’s channel, role, and server permissions, and Discord permission errors are returned to the caller.
• Destructive operations retain safeguards. Every destructive tool is annotated as destructive. Bulk delete, channel delete, bulk ban, and member pruning use dry-run-by-default previews; other destructive operations keep their existing validation and Discord audit-log reasons.
• Personal user-to-user Discord DMs cannot be accessed. The bot is not a user; it can only see server content it has permission to read and DMs sent directly to it.
• DMs to the bot are optional and off by default (collect_bot_dms).
• Stored messages remain local in your chosen data directory; nothing is uploaded anywhere.
• Content output is disabled by default. Returning readable excerpts through MCP requires both content storage and content output to be enabled, plus a per-call flag; otherwise, only counts, IDs, timestamps, and lexical labels are returned.
• Pseudonymisation and mention redaction apply to qualitative outputs (user IDs/names become generic labels; mentions and signed URL parameters are stripped).
• No external AI-provider calls and no embeddings/vector storage, the server is provider-neutral.
• Never commit a token. The bot token belongs in the extension config or a local .env, both of which are ignored by Git.
• The .mcpb format has no platform sandbox, so the server itself enforces these restrictions (read-only mode, content gates, one-writer locking); they are not delegated to the host.
• One writer per database. A file lock prevents two collectors (or a collector plus a CLI writer) from using one database at a time.

---

Developer installation

For development, direct MCP use, or CLI operation.

git clone  discord-mcp-server
cd discord-mcp-server
npm install
npm run build
npm test

Run the MCP server directly over stdio (add it to any MCP client config as a node dist/index.js command with a DISCORD_TOKEN env):

{
  "mcpServers": {
    "discord": {
      "command": "node",
      "args": ["/absolute/path/to/discord-mcp-server/dist/index.js"],
      "env": { "DISCORD_TOKEN": "your_bot_token_here" }
    }
  }
}

Or with Docker (see Operations):

docker build -t discord-mcp .
docker run --rm -i -e DISCORD_TOKEN=your_bot_token_here -v discord-analytics-data:/app/data discord-mcp

Creating your Discord bot

1. Go to discord.com/developers/applications → New Application.
2. Bot tab → Reset Token → copy the token (keep it private).
3. Enable the Server Members and Message Content privileged gateway intents (the server requests both by default).
4. OAuth2 → URL Generator: scope bot, then select only the permissions required by the profile below.
5. Invite the bot to your server with the generated URL.

Discord permission requirements

Exposing an MCP tool does not grant the bot Discord permission or modify the server. For normal posting, grant the bot the relevant channel permissions: View Channel, Send Messages, Read Message History, Add Reactions, Embed Links, Attach Files, and Send Messages in Threads where needed.

Forum posts use discord_create_forum_post and require View Channel, Send Messages, and Create Public Threads. Replies inside forum posts require Send Messages in Threads (shown as “Send Messages in Posts” in the forum interface). Scheduled-event tools use Discord’s event permissions: grant Create Events to create events and Manage Events to edit, cancel, or delete them; server configuration and role hierarchy can impose further limits.

Management tools require their matching permissions, including Manage Channels, Manage Roles, Manage Messages, Manage Webhooks, Kick Members, and Ban Members. Administrator is the simplest test configuration because it bypasses channel permission overwrites, but it grants extremely broad server access; prefer least privilege in normal use. Discord permission errors are returned by the tool and are never silently bypassed.

---

Configuration reference

Extension (MCPB) fields → environment variables

The desktop extension collects friendly fields and maps them to environment variables. Safe defaults are applied by the bundle:

Key environment variables (developer/CLI use)

See .env.example for the complete, commented list (including qualitative-analysis thresholds).

---

Operations

A generic operations CLI (node dist/cli/index.js , or the npm run scripts) makes the server safe to run without an MCP client. No operational command writes to Discord.

Exit codes: 0 success · 1 failure · 2 invalid argument · 3 config · 4 database · 5 Discord · 6 lock conflict · 7 partial.

Docker: multi-stage build, non-root user, no port exposed, /app/data volume, HEALTHCHECK runs the offline doctor. See docker-compose.example.yml. Run one collector per database.

Troubleshooting: run doctor for a full diagnosis; a stale lock after a hard crash is recovered with db-check --clear-stale-lock; on Windows, stop the process cleanly so the lock releases.

---

Limitations

• The desktop extension runs only while Claude Desktop invokes it; it is not a background daemon.
• It is local to the computer where it is installed; there is no remote/cloud access in this project.
• Voice attendance is prospective only, it cannot be reconstructed for periods when the collector was not running.
• Historical message sync depends on the bot’s channel access and on Discord’s retention.
• Private user-to-user DMs are inaccessible to the bot.
• Privately distributed extensions require manual installation of new bundle versions (there is no auto-updater).
• Remote MCP transport, OAuth, and a web dashboard are not included.
• Discord write success depends on the bot’s actual Discord permissions and role hierarchy; enabling MCP write mode does not grant those permissions.

---

Development status

The project was built in phases, all complete and covered by automated tests:

1. Read-only mode by default and central Discord-write protection.
2. Local SQLite analytics: historical sync and live message/reaction/thread/voice collection.
3. Deterministic community metrics: engagement, selected-user activity, staff response, training cadence, office-hour and weekly metrics.
4. Privacy-controlled qualitative analysis: topics, recurring questions, feedback signals, conversation context, and evidence packets with no external AI provider.
5. Operations CLI: doctor, database checks, process locks, backups, exports, pruning, and Docker readiness.
6. Claude Desktop MCP bundle packaging.
7. Packaged Discord writes enabled by default, with source-level read-only mode retained for restricted deployments.

---

Licence and attribution

Released under the MIT License. This project builds on the open-source Discord MCP server ecosystem; see the LICENSE file for the full terms and attribution. Bundle metadata uses the generic author “Discord MCP Server Contributors”.

---

Acknowledgement

This project is originally forked from PaSympa/discord-mcp.

The current implementation includes substantial modifications and additional functionality, including read-only protections, local SQLite analytics, reporting tools, privacy controls, operational tooling, and Claude Desktop extension packaging.