discord-mcp

# discord-mcp Full Documentation

FastMCP 3.2 Discord MCP server — 43 portmanteau operations, sampling, agentic workflow, and SOTA webapp.

## Overview

Connect your Discord bot to MCP clients. List servers, send messages, moderate members, search message history with RAG, and run agentic workflows from Cursor or Claude Desktop.

**Ports:** Backend 10756, Frontend 10757

## Tools

All Discord operations are consolidated into a single portmanteau tool:

### discord(operation=...)

| Operation | Description |
|-----------|-------------|
| list_guilds | List bot guilds |
| list_channels | List channels in a server (includes parent_id for tree layout) |
| get_channel | Get one channel's details (name, type, parent, topic, nsfw, slowmode) |
| update_channel | Rename / set topic / move into a category / position / nsfw / slowmode |
| update_guild | Rename a server or set its description |
| send_message | Send a message to a channel (rejects over-limit content, never truncates) |
| get_messages | Get recent messages from a channel |
| edit_message | Edit a bot-sent message |
| delete_message | Delete a bot-sent message |
| pin_message | Pin a message in a channel |
| unpin_message | Unpin a message |
| get_pinned_messages | List pinned messages in a channel |
| create_thread | Create a thread (standalone or from a message) |
| list_active_threads | List active threads in a channel |
| export_messages | Export channel messages as formatted markdown |
| create_channel | Create a channel in a server |
| delete_channel | Delete a channel permanently |
| create_dm | Create a DM channel with a user |
| create_guild | Create a server (user OAuth2 only) |
| create_invite | Create an invite link |
| list_invites | List server invites |
| revoke_invite | Revoke an invite |
| list_members | List guild members (requires GUILD_MEMBERS intent) |
| get_member | Get one guild member (requires GUILD_MEMBERS intent) |
| ban_member | Ban a user from a server (requires BAN_MEMBERS) |
| unban_member | Remove a ban |
| kick_member | Kick a user from a server (requires KICK_MEMBERS) |
| timeout_member | Timeout a member |
| list_roles | List server roles |
| create_role | Create a server role |
| delete_role | Delete a server role |
| assign_role | Assign a role to a member |
| remove_role | Remove a role from a member |
| get_guild_stats | Guild stats |
| get_channel_stats | Channel stats |
| get_audit_log | Get audit log entries with human-readable action labels, actor/target names (requires VIEW_AUDIT_LOG) |
| list_webhooks | List server webhooks |
| create_webhook | Create a webhook |
| execute_webhook | Execute a webhook |
| rag_ingest | Ingest channel messages into LanceDB for RAG |
| rag_query | Semantic search over ingested messages |

### discord_agentic_workflow(goal, ctx)

Multi-step agentic task using sampling.

### discord_help(topic)

Contextual help for any tool topic.

## Env Vars

| Variable | Default | Description |
|----------|---------|-------------|
| DISCORD_TOKEN | — | Bot token from Discord Developer Portal (primary) |
| DISCORD_BOT_TOKEN | — | Fallback if DISCORD_TOKEN not set |
| SECRETS_MCP_DISCORD_TOKEN | — | Fallback for secrets-mcp bridge |
| LANCEDB_DISCORD_PATH | data/discord_lancedb | LanceDB path for RAG |
| DISCORD_DEEPFANG_PREFLIGHT | 0 | Enable deepfang preflight check |
| PORT | 10756 | Backend port |
| DISCORD_SAMPLING_BASE_URL | http://127.0.0.1:11434/v1 | OpenAI-compatible sampling endpoint |
| DISCORD_SAMPLING_MODEL | auto | Model for sampling; when unset, auto-resolves to an installed Ollama model (prefers llama3.2:3b) |
| DISCORD_SAMPLING_USE_CLIENT_LLM | 0 | Prefer host LLM for sampling |
| DISCORD_RATE_LIMIT_MESSAGES_PER_MINUTE | 10 | Max messages per minute |
| DISCORD_COMMS_AUTOSTART | 0 | Autostart inbound watcher |
| DISCORD_COMMS_CHANNELS | — | Comma-separated channel IDs to watch |
| DISCORD_TAURI | 0 | Set when running inside Tauri WebView |

## Architecture

- FastAPI backend with FastMCP 3.2 dual transport (stdio + HTTP)
- Portmanteau tool: `discord(operation=...)` dispatches internally
- LanceDB for RAG (optional, requires sentence-transformers)
- Rate limiter with per-channel and global limits
- Comms lane: background message watcher with webhook delivery
- Sampling handler (Ollama or client LLM) for agentic workflows
- Skills directory at `src/discord_mcp/skills/`
- FastAPI app at `src/discord_mcp/server.py`
- Webapp at `webapp/` (Vite + React + Tailwind)

## Troubleshooting

- **Discord 429 rate limits**: Server auto-retries with exponential backoff
- **Missing intents**: Ensure GUILD_MEMBERS, MESSAGE_CONTENT intents in Developer Portal
- **Token invalid**: Regenerate bot token, update .env
- **No servers found**: Bot must be invited to at least one server
- **"LLM completion failed: 404"**: The sampling model is not installed — run `ollama pull llama3.2:3b` or set `DISCORD_SAMPLING_MODEL` to a pulled model
- **Webapp blank**: Ensure backend is running on port 10756, frontend 10757