Discord MCP

Repository: github.com/sandraschi/discord-mcp

FastMCP 3.1 Discord MCP-Server mit Sampling (server-seitiges Ollama / OpenAI-kompatibel oder Client-LLM), agentenbasiertem Workflow (discord_agentic_workflow), Skills (SkillsDirectoryProvider + skill:///SKILL.md), Prompts und einem 2026 Fleet-Style Dashboard (React + Vite + Tailwind, dunkles Glas-Design).

Ports

• Backend: 10756 REST (/api/v1/) + MCP streamable HTTP unter /mcp

• Frontend: 10757

Related MCP server: Discord Notifications MCP Server

Einrichtung

1. Erstellen Sie einen Bot im Discord Developer Portal. Kopieren Sie das Bot-Token.

2. Laden Sie den Bot auf Ihren Server ein (OAuth2 URL Generator, Scope: bot).

3. Kopieren Sie .env.example nach .env im Repository-Root (discord-mcp/.env) und setzen Sie DISCORD_TOKEN=... (ohne Anführungszeichen). Das Backend lädt diese Datei beim Start (python-dotenv). Starten Sie den Server neu, nachdem Sie die .env geändert haben. Wenn das Token bereits in der Systemumgebung oder in Cursor MCP env gesetzt ist, hat dieser Wert Vorrang (.env überschreibt keine bestehenden Variablen).

4. Für lokales agentenbasiertes Sampling (wenn der MCP-Host kein Sampling bereitstellt): Führen Sie Ollama aus und setzen Sie optional DISCORD_SAMPLING_BASE_URL / DISCORD_SAMPLING_MODEL. Setzen Sie DISCORD_SAMPLING_USE_CLIENT_LLM=1, wenn Sie möchten, dass das Host-LLM das Sampling übernimmt und der Server-Handler nur als Fallback dient.

Ausführung

• Webapp (Backend + Dashboard): Führen Sie vom Repository-Root aus .\start.ps1 oder start.bat aus, oder von webapp/: .\start.ps1.

• Nur Backend: uv run python -m discord_mcp.server --mode dual --port 10756

• Stdio (nur MCP): uv run python -m discord_mcp.server --mode stdio

Cursor MCP

• Dieses Repository als Workspace-Root: .cursor/mcp.json registriert discord-mcp (stdio). Setzen Sie DISCORD_TOKEN in der env-Sektion dieser Datei oder verlassen Sie sich auf Ihre Shell-Umgebung. Laden Sie MCP neu / starten Sie Cursor nach Änderungen neu.

• Global / Multi-Root-Merge: Kopieren Sie den discord-mcp-Block aus cursor-config-template.json in Ihre Benutzer-MCP-JSON (Windows: %USERPROFILE%\.cursor\mcp.json). Passen Sie cwd an Ihren Klon-Pfad an, falls Sie nicht den Standard D:/Dev/repos/discord-mcp verwenden.

MCP HTTP (Remote / Inspector)

• Endpunkt: http://localhost:10756/mcp (streamable HTTP, FastMCP 3.1.0)

• Discovery / Manifest: GET /api/v1/meta

• Status: GET /api/v1/health (enthält Sampling-Status)

Tools

• discord(operation=) Portmanteau: list_guilds, list_channels, send_message, get_messages, get_guild_stats, create_channel, create_guild, create_invite, list_invites, revoke_invite, list_members, get_member, list_active_threads, rag_ingest, rag_query. create_guild erfordert Benutzer-OAuth2 (Bot 403). list_members / get_member erfordern das GUILD_MEMBERS-Intent.

• discord_help(category=, topic=) Mehrstufige Hilfe.

• discord_agentic_workflow(goal, ctx) High-Level-Ziel via ctx.sample + Tools (SEP-1577). Gibt ein strukturiertes dict zurück (success, message, recommendations oder Fehlerfelder).

Prompts (registriert)

discord_quick_start, discord_diagnostics, discord_moderation_playbook, discord_rag_workflow, discord_invite_operations

Skills

Gebündelt unter src/discord_mcp/skills/<name>/SKILL.md, verfügbar als MCP-Ressourcen (skill://). Gelistet im Dashboard unter Skills und via GET /api/v1/skills.

Ressourcen

• resource://discord-mcp/capabilities Kurze Zusammenfassung der Fähigkeiten für Clients.

API (REST)

• GET /api/v1/health Status, token_set, Ratenbegrenzungen, Sampling, mcp_http_path

• GET /api/v1/meta Tools, Prompts, Ressourcen, Skills-Root, Sampling

• GET /api/v1/skills Gebündelte Skill-Vorschauen (Dashboard)

• GET /api/v1/guilds Gilden auflisten (Proxy zum Tool)

• GET /api/v1/guilds/{guild_id}/channels Kanäle auflisten

• (Siehe OpenAPI unter /docs für die vollständige Liste.)

Discord HTTP 429 (API-Ratenbegrenzungen)

Discord erzwingt routenbasierte Limits für die REST-API. Bei HTTP 429 wartet der Server nun auf retry_after (aus dem Antwort-Body oder dem Retry-After-Header) und wiederholt dieselbe Anfrage bis zu 5 Mal, bevor ein Fehler zurückgegeben wird. Wenn Sie danach immer noch 429 sehen, verlangsamen Sie die Anfragen (z. B. weniger parallele Nachrichtenabrufe, kleinere RAG-Ingest-Batches) oder warten Sie eine Minute, insbesondere wenn "global": true in der Antwort von Discord erscheint (selten; weist auf ein breiteres Limit hin).

Sicherheit und Ratenbegrenzungen (Anti-Spam)

Schreiboperationen sind ratenbegrenzt, damit der Bot nicht als Spambot missbraucht werden kann:

• Nachrichten: max. 10/Min. global, max. 3/Min. pro Kanal, mind. 5 Sek. zwischen dem Senden (konfigurierbar).

• Kanäle: max. 5 pro Minute erstellt.

• Einladungen: max. 5 pro Minute (DISCORD_RATE_LIMIT_INVITES_PER_MINUTE).

• Nachrichtenlänge: begrenzt auf 2000 (Discord-Maximum); überschreibbar mit DISCORD_MAX_MESSAGE_LENGTH.

Env: DISCORD_RATE_LIMIT_MESSAGES_PER_MINUTE, DISCORD_RATE_LIMIT_MESSAGES_PER_CHANNEL_PER_MINUTE, DISCORD_RATE_LIMIT_CHANNELS_PER_MINUTE, DISCORD_MAX_MESSAGE_LENGTH, DISCORD_MIN_MESSAGE_INTERVAL_SECONDS. Wenn ein Limit erreicht wird, gibt das Tool success: false, rate_limited: true und einen erklärenden error zurück. Die aktuelle Konfiguration finden Sie unter GET /api/v1/health im Bereich rate_limit.

Dokumentation

• docs/README.md Dokumentations-Index

• docs/TECHNICAL.md Architektur, Env, Discord 429, MCP /mcp

• CHANGELOG.md Versionshinweise

Standards

• FastMCP 3.1.0: Anweisungen, Sampling-Handler, Skills-Provider, strikte Validierung, streamable HTTP-Mount.

• Webapp: start.ps1, Ports 10756/10757, dunkles Glas-Layout, Statusleiste oben, Aktivitätsprotokoll, Tools / Skills / Apps-Seiten.

🛡️ Industrial Quality Stack

Dieses Projekt hält sich an SOTA 14.1 Industriestandards für hochpräzise agentenbasierte Orchestrierung:

• Python (Core): Ruff für Linting und Formatierung. Null-Toleranz für print-Anweisungen in Core-Handlern (T201).

• Webapp (UI): Biome für Linting im Sub-Millisekundenbereich. Strikte noConsoleLog-Durchsetzung.

• Protokoll-Konformität: Gehärtete stdout/stderr-Isolierung, um eine absturzsichere JSON-RPC-Kommunikation zu gewährleisten.

• Automatisierung: Justfile Rezepte für alle Fleet-Operationen (just lint, just fix, just dev).

• Sicherheit: Automatisierte Audits via bandit und safety.