betterdiscord-mcp

Un servidor MCP que permite a un agente de IA (como Claude) leer datos de servidores de Discord a través de tu propia cuenta. Se empareja con un plugin de BetterDiscord, por lo que el lado de Python nunca maneja tu token — los datos se leen directamente desde el cliente de Discord ya autenticado.

GitHubPrueba este MCPPatrocinado

Documentación

betterdiscord-mcp

Un servidor MCP que permite a un agente de IA (como Claude) leer datos de servidores de Discord a través de tu propia cuenta. Se complementa con un plugin de BetterDiscord, por lo que el lado de Python nunca maneja tu token — los datos se leen directamente del cliente de Discord ya autenticado.

Claude ──stdio──> Python MCP ──WebSocket──> BetterDiscord plugin ──> Discord

⚠️ Aviso legal — lee esto primero

Esta es una herramienta de self-bot. Automatizar una cuenta personal de Discord y modificar el cliente (BetterDiscord) viola los Términos de Servicio de Discord y puede resultar en la suspensión de tu cuenta.

Úsalo solo en tu propia cuenta y bajo tu propio riesgo.
Los autores no se hacen responsables por cuentas suspendidas ni por cualquier otra consecuencia.
Leer datos ya cargados del cliente es más discreto que un self-bot HTTP crudo, pero el riesgo no es cero. Haz solicitudes con poca frecuencia y en lotes pequeños.
No lo uses para recopilar, redistribuir o publicar datos privados de otras personas. Respeta la privacidad de los servidores en los que estás.

Si no te sientes cómodo con estos términos, usa un bot oficial de Discord a través del Portal de Desarrolladores.

Requisitos

Python 3.10+
uv (gestor de paquetes/entorno)
BetterDiscord instalado
Un cliente compatible con MCP (Claude Desktop o Claude Code)

Instalación

1. Servidor Python (vía uv):

git clone https://github.com/encryrose/betterdiscord-mcp.git
cd betterdiscord-mcp
uv sync

2. Plugin de BetterDiscord:

Copia plugin/DiscordMcpBridge.plugin.js en tu carpeta de plugins de BD:
- Windows: %AppData%\BetterDiscord\plugins\
- macOS: ~/Library/Application Support/BetterDiscord/plugins/
- Linux: ~/.config/BetterDiscord/plugins/
En Discord: Configuración → Plugins → activa DiscordMcpBridge.
Asegúrate de que BRIDGE_PORT en la parte superior del plugin coincida con tu .env (por defecto 8787).

3. Registra el servidor MCP con tu cliente:

Claude Code (CLI):

claude mcp add discord -- uv --directory /path/to/betterdiscord-mcp run discord-mcp

Claude Desktop — añade a claude_desktop_config.json:

{
  "mcpServers": {
    "discord": {
      "command": "uv",
      "args": ["--directory", "/path/to/betterdiscord-mcp", "run", "discord-mcp"]
    }
  }
}

Reemplaza /path/to/betterdiscord-mcp con la ruta absoluta donde clonaste el repositorio. Si uv no está en el PATH de tu cliente, usa la ruta completa al ejecutable uv en command.

Cómo funciona

Al iniciar, el servidor MCP abre un puente WebSocket en 127.0.0.1:8787.
El plugin dentro de Discord se conecta al puente (verás una notificación de "bridge connected").
El agente llama a las herramientas; el plugin lee las tiendas internas de Flux de Discord y devuelve los datos.

Ningún token se envía al lado de Python — el plugin se ejecuta dentro de tu cliente ya autenticado.

Herramientas

Herramienta	Propósito
`bridge_status`	Verifica si el plugin está conectado
`ping`	Verificación de salud ligera: versión del plugin + mapa de módulos resueltos
`diagnostics`	Muestra qué módulos internos de Discord se resolvieron (depuración)
`list_guilds`	Lista los servidores que el cliente puede ver
`list_channels`	Lista los canales de texto de un servidor
`get_messages`	Lee el historial de un canal (pagina con `before`; filtra por `author_id` / `after`; `humanize` resuelve menciones)
`search_messages`	Búsqueda nativa de Discord en un servidor
`search_local`	Búsqueda de texto completo sin conexión (SQLite FTS5) sobre `exports/*.json`
`get_message_by_link`	Obtiene un solo mensaje desde un enlace de mensaje de Discord
`get_reactions`	Lista los usuarios que reaccionaron a un mensaje con un emoji dado
`list_dms`	Lista los DMs directos y grupales de la cuenta
`list_threads`	Lista hilos o publicaciones de foro (carga publicaciones de foro no almacenadas en caché; incluye `first_message`)
`list_threads_paginated`	Hilos/publicaciones de foro paginados (`offset`/`limit`, devuelve `{threads, hasMore, total}`)
`read_thread`	Lee los mensajes de un hilo / publicación de foro en orden cronológico
`get_pins`	Lista los mensajes fijados de un canal o hilo
`get_channel_info`	Metadatos de un canal o hilo
`get_guild_info`	Metadatos del servidor: roles, canales, número de miembros, características, nivel de impulso
`resolve_id`	Clasifica cualquier snowflake como servidor/canal/hilo/usuario/mensaje
`list_members`	Miembros actualmente conocidos por el cliente (`resolve_role_names` añade nombres de roles)
`get_roles`	Lista los roles de un servidor (id, nombre, color, posición, permisos)
`get_user_info`	Busca un usuario por id
`export_channel`	Vuelca el historial de un canal a `exports/*.json`
`export_attachments`	Descarga los adjuntos de un canal a `exports/` con un manifiesto
`download_attachment`	Descarga un solo adjunto del CDN de Discord a `exports/`
`channel_stats`	Análisis sin conexión desde una exportación de canal (por usuario, línea de tiempo, gráfico de respuestas)

Flujo típico

Comienza con bridge_status. Si está conectado: list_guilds → list_channels → get_messages / search_messages / export_channel.

Solución de problemas

"Plugin not connected" — ¿Está Discord ejecutándose? ¿Está el plugin habilitado? ¿Coinciden los puertos en .env y el plugin?
"Module not found" / "is not a function" — Discord se actualizó y los selectores de Webpack en _resolveModules() se desviaron. Ejecuta diagnostics para ver qué se resolvió, luego corrige los filtros de módulos.
Historial vacío — Desplázate manualmente por el canal una vez para que el cliente cargue los mensajes, luego reintenta.

Desarrollo

Instala el proyecto junto con sus herramientas de desarrollo (pytest, pytest-asyncio, ruff):

uv sync --group dev

Ejecuta la suite de pruebas:

uv run pytest

Lint del código:

uv run ruff check .

Las pruebas viven en tests/ y ejercitan el puente WebSocket (discord_mcp.bridge.Bridge) directamente: inician el servidor en un puerto poco común, conectan un plugin falso con el cliente websockets, y verifican que un round-trip JSON-RPC devuelve el resultado esperado. No se necesita un cliente real de Discord.

Registro con Claude Code

Una vez instalado, registra el servidor con Claude Code:

claude mcp add discord -- uv --directory /path/to/betterdiscord-mcp run discord-mcp

Reemplaza /path/to/betterdiscord-mcp con la ruta absoluta a tu clon.

Integración continua

GitHub Actions (.github/workflows/ci.yml) se ejecuta en cada push y pull request con dos trabajos:

python — instala uv, ejecuta uv sync --group dev, luego uv run ruff check . y uv run pytest -q.
plugin-syntax — valida el plugin de BetterDiscord con node --check plugin/DiscordMcpBridge.plugin.js.

Capturas de pantalla

TODO: añadir un GIF corto del agente leyendo un canal.

Licencia

MIT — ver LICENSE. Se proporciona tal cual, sin garantía. El uso de este software es tu responsabilidad.