@devli13/mcp-discord

Un servidor MCP para Discord. Envía mensajes, modera, gestiona canales, inspecciona servidores — desde Claude Code, agentes de Paperclip, Gemini CLI o cualquier cliente compatible con MCP.

Wrapper REST puro. Sin Gateway. Sin base de datos. Solo la API v10 de Discord como 26 herramientas bien documentadas, con limitación de tasa por ruta y resultados de error estructurados.

Por qué

La API de Discord es extensa y poco amigable para los agentes cuando se llama mediante curl sin procesar. Los agentes alcanzan límites de tasa, gestionan mal los errores 429, manejan mal los motivos del registro de auditoría y olvidan los cursores de paginación. Este MCP soluciona eso de una vez, para que los agentes puedan centrarse en la intención: "eliminar ese mensaje de spam", "publicar el resumen diario en #mod-log", "silenciar a @usuario durante una hora".

También es genial para los humanos. Conectado a Claude Code, puedes decir "resume los últimos 50 mensajes en mi canal #dev de Discord" y Claude simplemente lo hace.

Related MCP server: Discord Bridge MCP Server

Instalación

npm install -g @devli13/mcp-discord

O mediante npx (sin instalación):

DISCORD_BOT_TOKEN=<your-token> npx -y @devli13/mcp-discord

Configuración

1. Crea un bot de Discord

1. Ve a https://discord.com/developers/applications → New Application

2. Añade un Bot a la aplicación

3. Copia el token del bot — este es tu DISCORD_BOT_TOKEN

4. Invita al bot a tu servidor usando el generador de URL OAuth2 (alcance: bot). Elige los permisos según lo que necesites que haga el MCP (p. ej., Gestionar mensajes para eliminarlos, Moderar miembros para silenciarlos)

2. Conéctalo a tu cliente MCP

Claude Code:

claude mcp add discord \
  --env DISCORD_BOT_TOKEN=<your-token> \
  -- npx -y @devli13/mcp-discord

Paperclip mcp-gateway (.mcp.json):

{
  "mcpServers": {
    "discord": {
      "command": "npx",
      "args": ["-y", "@devli13/mcp-discord"],
      "env": {
        "DISCORD_BOT_TOKEN": "<your-token>"
      }
    }
  }
}

Gemini CLI (~/.gemini/config.json):

{
  "mcpServers": {
    "discord": {
      "command": "npx",
      "args": ["-y", "@devli13/mcp-discord"]
    }
  }
}

3. (Opcional) Habilita los intents privilegiados

Si deseas listar los miembros del servidor (discord_list_members) o usar este MCP junto con el plugin complementario para eventos entrantes, habilita Server Members Intent y Message Content Intent en la configuración del Portal de Desarrolladores de tu bot. Estos no son necesarios para la mayoría de las operaciones de MCP, solo para puntos finales específicos.

Referencia de herramientas

Todas las herramientas tienen el prefijo discord_* y devuelven un blob JSON (en caso de éxito) o un mensaje de error formateado (en caso de fallo). Ninguna lanza excepciones: cada herramienta devuelve un resultado de cadena utilizable.

Mensajes (8)

Reacciones (3)

Canales e hilos (5)

Moderación (6)

Información del servidor (4)

No incluido (por diseño):

• ban/unban — deliberado. Usa la interfaz de Discord; las acciones irreversibles no deberían estar a una llamada de agente de distancia

• Crear/eliminar/editar canales — alto radio de impacto, usa la interfaz

• CRUD de Webhooks — no es necesario para la mayoría de los flujos de agentes; se puede añadir en una versión futura

• Operaciones de voz, gestión de stickers/emojis — fuera del alcance de la v0.1

Ejemplo: resumir un canal mediante Claude Code

User: Summarize the last 30 messages in the #dev channel of my Discord server, guild ID 1234...

Claude (calls discord_list_channels → finds #dev → calls discord_list_messages → writes summary)

Ejemplo: resumen diario del agente de Paperclip

// From an agent's prompt:
"Post the daily digest to channel 1234. Summarize the last 24h of activity
using discord_list_messages with limit=100, then format as an embed via
discord_send_message."

Manejo de errores

Cada herramienta devuelve un resultado de texto utilizable. En caso de error:

Error (DISCORD_50001, HTTP 403): Missing Access
Details: [...]
(This error is transient and may succeed on retry.)

El MCP ya maneja los reintentos internamente para 429 (límites de tasa) y 5xx (errores del servidor), con retroceso exponencial.

Límites de tasa

Discord tiene dos capas de límites de tasa:

1. Por ruta — cada punto final de la API tiene buckets independientes. Este MCP serializa las solicitudes por (método + plantilla de ruta) para evitar superar el límite de 429.

2. Global — por bot, en todos los puntos finales. El MCP respeta los encabezados Retry-After globalmente.

No deberías tener que pensar en esto. Si alcanzas el límite global repetidamente, probablemente estés haciendo algo que requiere intervención humana.

Seguridad

• Nunca subas tu token de bot. Este MCP lo lee de la variable de entorno DISCORD_BOT_TOKEN al iniciarse.

• Usa URLs de invitación con el mínimo privilegio. No des permisos de Administrador a los bots si solo necesitas Gestionar mensajes.

• Motivos del registro de auditoría — todas las herramientas de moderación aceptan un argumento reason que aparece en el registro de auditoría de Discord. Úsalo.

Desarrollo

git clone https://github.com/devli13/mcp-discord.git
cd mcp-discord
npm install
npm test           # smoke tests (no live Discord calls)
npm run lint       # syntax check all files
npm start          # boot server over stdio (needs DISCORD_BOT_TOKEN)

Proyecto complementario — eventos entrantes

Este MCP maneja llamadas REST salientes (enviar, eliminar, moderar). No mantiene un WebSocket de Discord Gateway, por lo que no puede reaccionar a eventos entrantes (un usuario mencionando al bot, mensajes directos, nuevos miembros uniéndose).

Para eventos de Discord entrantes en una configuración de Paperclip, usa @devli13/paperclip-plugin-discord — un fork de @mvanhorn/paperclip-plugin-discord con enrutamiento de menciones de forma libre, soporte para mensajes directos, una cola de mensajes serializada por contexto y relleno de menciones durante el tiempo de inactividad.

Los dos proyectos están diseñados para trabajar juntos: el plugin recibe eventos e invoca a tu agente; el agente usa este MCP para responder y moderar. Usa uno o ambos dependiendo de tu configuración.

Atribución

Consulta ATTRIBUTION.md. Versión corta: construido junto al fork de paperclip-plugin-discord de @mvanhorn, cuyo manejo de Gateway inspiró los patrones de diseño aquí.

Licencia

MIT — consulta LICENSE.