list_bans
Retrieve a list of banned users from a Discord server to review moderation actions and manage community access.
Instructions
List banned users for the server.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| server_id | No | ||
| limit | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- src/discord_mcp/server.py:1326-1358 (handler)Handler function that implements the 'list_bans' tool. Fetches banned users using guild.bans() iterator (limited), formats their names, IDs, and ban reasons into a markdown list.
async def list_bans( server_id: str | int | None = None, limit: int = 20, ctx: Context = None, ) -> str: # type: ignore[override] """List banned users for the server.""" assert ctx is not None bot, config = await _acquire(ctx) guild_id = _resolve_guild_id(config, server_id) guild = await _ensure_guild(bot, guild_id) limit = max(1, min(limit, 100)) entries: list[discord.guild.BanEntry] = [] try: async for entry in guild.bans(limit=None): entries.append(entry) if len(entries) >= limit: break except discord.DiscordException as exc: raise _describe_discord_error("list bans", exc) from exc if not entries: return f"No banned users found for {guild.name}." lines = [f"**Banned users for {guild.name} (showing {len(entries)}):**"] for entry in entries: user = entry.user reason_text = entry.reason or "No reason provided" lines.append(f"• {user.display_name} ({user.id}) – Reason: {reason_text}") return "\n".join(lines)