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.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "list_bans"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| server_id | No | ||
| limit | No |
Output 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)