discord-admin-mcp

Servidor MCP em Python para administrar servidores Discord a partir do Claude Code (ou qualquer cliente MCP). Usa a API REST v10 do Discord através do seu próprio bot.

Ferramentas

As ações aceitam reason, que é registrado no audit log do servidor. Ferramentas destrutivas indicam na descrição que o assistente deve confirmar com você antes de executar.

Related MCP server: Discord MCP

Requisitos

• Python 3.11+

• uv

1. Criar o bot

1. Acesse o Discord Developer Portal e clique em New Application.

2. Na aba Bot:

   • ative Server Members Intent;

   • clique em Reset Token e copie o token (formato xxxx.yyyy.zzzz, ~70 caracteres — não confunda com o Client Secret da aba OAuth2).

3. (Opcional, recomendado) Para que só você possa instalar o bot: em Installation, defina Install Link como None; depois, em Bot, desmarque Public Bot.

2. Configurar o token

Nunca coloque o token no código nem faça commit dele.

Windows:

setx DISCORD_BOT_TOKEN "seu-token"

Linux/macOS:

export DISCORD_BOT_TOKEN="seu-token"

Ou copie .env.example para .env e carregue-o no seu shell (o .env está no .gitignore).

3. Instalar

git clone <url-deste-repositorio>
cd discord-cli
uv sync

Teste a conexão:

uv run python -c "import discord_admin_mcp as d; print(d.whoami())"

4. Convidar o bot para o servidor

Troque SEU_CLIENT_ID pelo Application ID do seu app:

https://discord.com/oauth2/authorize?client_id=SEU_CLIENT_ID&scope=bot&permissions=1099914357943

Esse valor concede apenas permissões de gestão (sem Administrador): ver audit log, gerenciar servidor, cargos, canais, apelidos e mensagens, expulsar, banir, moderar (castigo), criar convites, ver canais, enviar mensagens e ler histórico.

Depois de autorizar, em Configurações do servidor → Cargos, arraste o cargo do bot para acima dos cargos que ele deve gerenciar — o Discord só permite que o bot altere cargos e membros abaixo dele.

5. Registrar no Claude Code

claude mcp add discord-admin --scope user -- uv --directory /caminho/para/discord-cli run discord-admin-mcp

Abra uma nova sessão e peça, por exemplo: "liste os membros sem cargo" ou "crie o canal #avisos na categoria Comercial".

Outros clientes MCP

{
  "mcpServers": {
    "discord-admin": {
      "command": "uv",
      "args": ["--directory", "/caminho/para/discord-cli", "run", "discord-admin-mcp"],
      "env": { "DISCORD_BOT_TOKEN": "seu-token" }
    }
  }
}

Segurança

• O token só é lido da variável de ambiente DISCORD_BOT_TOKEN.

• Quem tem o token controla o bot com todas as permissões dele. Se vazar, use Reset Token no portal imediatamente.

• Conceda ao bot só as permissões necessárias e posicione o cargo dele com cuidado.

Contribuindo

Issues e pull requests são bem-vindos.

Licença

MIT