betterdiscord-mcp

Um servidor MCP que permite que um agente de IA (como o Claude) leia dados de servidores do Discord através da sua própria conta. Ele funciona em conjunto com um plugin do BetterDiscord, de modo que o lado Python nunca lida com seu token — os dados são lidos diretamente do cliente Discord já autenticado.

GitHubExperimente este MCPPatrocinado

Documentação

betterdiscord-mcp

Um servidor MCP que permite que um agente de IA (como o Claude) leia dados de servidores do Discord através da sua própria conta. Ele funciona em conjunto com um plugin do BetterDiscord, para que o lado Python nunca manipule seu token — os dados são lidos diretamente do cliente Discord já autenticado.

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

⚠️ Aviso — leia isto primeiro

Esta é uma ferramenta de self-bot. Automatizar uma conta pessoal do Discord e modificar o cliente (BetterDiscord) viola os Termos de Serviço do Discord e pode resultar no banimento da sua conta.

Use apenas na sua própria conta e por sua conta e risco.
Os autores não se responsabilizam por contas banidas ou quaisquer outras consequências.
Ler dados já carregados no cliente é mais discreto do que um self-bot HTTP bruto, mas o risco não é zero. Faça requisições com pouca frequência e em pequenos lotes.
Não use para coletar, redistribuir ou publicar dados privados de outras pessoas. Respeite a privacidade dos servidores em que você está.

Se você não se sentir confortável com estes termos, use um bot oficial do Discord através do Portal do Desenvolvedor.

Requisitos

Python 3.10+
uv (gerenciador de pacotes/execução)
BetterDiscord instalado
Um cliente compatível com MCP (Claude Desktop ou Claude Code)

Instalação

1. Servidor Python (via uv):

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

2. Plugin do BetterDiscord:

Copie plugin/DiscordMcpBridge.plugin.js para a sua pasta de plugins do BD:
- Windows: %AppData%\BetterDiscord\plugins\
- macOS: ~/Library/Application Support/BetterDiscord/plugins/
- Linux: ~/.config/BetterDiscord/plugins/
No Discord: Configurações → Plugins → ative DiscordMcpBridge.
Certifique-se de que BRIDGE_PORT no topo do plugin corresponda ao seu .env (padrão 8787).

3. Registre o servidor MCP no seu cliente:

Claude Code (CLI):

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

Claude Desktop — adicione em claude_desktop_config.json:

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

Substitua /path/to/betterdiscord-mcp pelo caminho absoluto onde você clonou o repositório. Se uv não estiver no PATH do seu cliente, use o caminho completo para o executável uv em command.

Como funciona

Ao iniciar, o servidor MCP abre uma ponte WebSocket em 127.0.0.1:8787.
O plugin dentro do Discord conecta-se à ponte (você verá uma notificação "bridge connected").
O agente chama as ferramentas; o plugin lê os stores internos do Flux do Discord e retorna os dados.

Nenhum token é enviado para o lado Python — o plugin roda dentro do seu cliente já autenticado.

Ferramentas

Ferramenta	Finalidade
`bridge_status`	Verificar se o plugin está conectado
`ping`	Verificação de saúde leve: versão do plugin + mapa de módulos resolvidos
`diagnostics`	Mostrar quais módulos internos do Discord foram resolvidos (depuração)
`list_guilds`	Listar servidores que o cliente pode ver
`list_channels`	Listar os canais de texto de um servidor
`get_messages`	Ler o histórico de um canal (paginar com `before`; filtrar por `author_id` / `after`; `humanize` resolve menções)
`search_messages`	Busca nativa do Discord em um servidor
`search_local`	Busca offline de texto completo (SQLite FTS5) em `exports/*.json`
`get_message_by_link`	Buscar uma única mensagem a partir de um link de mensagem do Discord
`get_reactions`	Listar usuários que reagiram a uma mensagem com um determinado emoji
`list_dms`	Listar os DMs diretos e em grupo da conta
`list_threads`	Listar threads ou posts de fórum (carrega posts de fórum não armazenados em cache; inclui `first_message`)
`list_threads_paginated`	Threads/posts de fórum paginados (`offset`/`limit`, retorna `{threads, hasMore, total}`)
`read_thread`	Ler as mensagens de um thread / post de fórum em ordem cronológica
`get_pins`	Listar mensagens fixadas de um canal ou thread
`get_channel_info`	Metadados de um canal ou thread
`get_guild_info`	Metadados do servidor: cargos, canais, contagem de membros, recursos, nível de boost
`resolve_id`	Classificar qualquer snowflake como servidor/canal/thread/usuário/mensagem
`list_members`	Membros atualmente conhecidos pelo cliente (`resolve_role_names` adiciona nomes de cargos)
`get_roles`	Listar os cargos de um servidor (id, nome, cor, posição, permissões)
`get_user_info`	Buscar um usuário por id
`export_channel`	Exportar o histórico de um canal para `exports/*.json`
`export_attachments`	Baixar os anexos de um canal para `exports/` com um manifesto
`download_attachment`	Baixar um único anexo do CDN do Discord para `exports/`
`channel_stats`	Análises offline a partir de uma exportação de canal (por usuário, linha do tempo, grafo de respostas)

Fluxo típico

Comece com bridge_status. Se conectado: list_guilds → list_channels → get_messages / search_messages / export_channel.

Solução de problemas

"Plugin not connected" — O Discord está rodando? O plugin está ativado? As portas correspondem em .env e no plugin?
"Module not found" / "is not a function" — O Discord foi atualizado e os seletores do Webpack em _resolveModules() ficaram desatualizados. Execute diagnostics para ver o que foi resolvido e depois corrija os filtros de módulos.
Histórico vazio — Role o canal manualmente uma vez para que o cliente carregue as mensagens e tente novamente.

Desenvolvimento

Instale o projeto junto com suas ferramentas de desenvolvimento (pytest, pytest-asyncio, ruff):

uv sync --group dev

Execute a suíte de testes:

uv run pytest

Verifique o código:

uv run ruff check .

Os testes estão em tests/ e exercitam a ponte WebSocket (discord_mcp.bridge.Bridge) diretamente: eles iniciam o servidor em uma porta incomum, conectam um plugin falso com o cliente websockets e verificam se um round-trip JSON-RPC retorna o resultado esperado. Nenhum cliente Discord real é necessário.

Registrando com o Claude Code

Após a instalação, registre o servidor com o Claude Code:

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

Substitua /path/to/betterdiscord-mcp pelo caminho absoluto para o seu clone.

Integração contínua

GitHub Actions (.github/workflows/ci.yml) roda em cada push e pull request com dois jobs:

python — instala uv, executa uv sync --group dev, depois uv run ruff check . e uv run pytest -q.
plugin-syntax — valida o plugin do BetterDiscord com node --check plugin/DiscordMcpBridge.plugin.js.

Capturas de tela

TODO: adicionar um GIF curto do agente lendo um canal.

Licença

MIT — veja LICENSE. Fornecido como está, sem garantias. O uso deste software é de sua responsabilidade.