ban_user
Ban a user from a chat by user ID and chat ID, with optional duration and message revocation.
Instructions
Ban a user from a chat.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| chat_id | Yes | ||
| user_id | Yes | ||
| ban_duration_hours | No | ||
| revoke_messages | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ok | Yes | ||
| error | No | ||
| user_id | No | ||
| permanent | No | ||
| until | No |
Implementation Reference
- aiogram_mcp/tools/chats.py:104-151 (handler)The ban_user tool handler — an async function decorated with @mcp.tool that bans a user from a chat via bot.ban_chat_member(), supporting optional ban_duration_hours and revoke_messages. Wraps result in BanUserResult and includes audit logging.
async def ban_user( chat_id: int, user_id: int, ban_duration_hours: int | None = None, revoke_messages: bool = False, ) -> BanUserResult: """Ban a user from a chat.""" if not ctx.is_chat_allowed(chat_id): result = BanUserResult(ok=False, error=f"Chat {chat_id} is not allowed.") if ctx.audit_logger: ctx.audit_logger.log( "ban_user", {"chat_id": chat_id, "user_id": user_id}, result.ok, result.error, ) return result until_date = None if ban_duration_hours: until_date = datetime.now(timezone.utc) + timedelta(hours=ban_duration_hours) try: if ctx.rate_limiter: await ctx.rate_limiter.acquire() await ctx.bot.ban_chat_member( chat_id=chat_id, user_id=user_id, until_date=until_date, revoke_messages=revoke_messages, ) result = BanUserResult( ok=True, user_id=user_id, permanent=until_date is None, until=until_date.isoformat() if until_date else None, ) except (TelegramBadRequest, TelegramForbiddenError) as exc: result = BanUserResult(ok=False, error=str(exc)) if ctx.audit_logger: ctx.audit_logger.log( "ban_user", {"chat_id": chat_id, "user_id": user_id}, result.ok, result.error, ) return result - aiogram_mcp/tools/chats.py:28-31 (schema)BanUserResult model — a ToolResponse subclass with fields: user_id (int), permanent (bool), until (str), used as the return type of the ban_user handler.
class BanUserResult(ToolResponse): user_id: int | None = None permanent: bool | None = None until: str | None = None - aiogram_mcp/tools/chats.py:101-103 (registration)Registration gate: the @mcp.tool decorator is applied to ban_user() only if allowed_tools is None or contains 'ban_user'.
if allowed_tools is None or "ban_user" in allowed_tools: @mcp.tool - aiogram_mcp/server.py:90-90 (registration)Call to register_chat_tools() in the MCP server's _register_tools method, which triggers the registration of ban_user among other chat tools.
register_chat_tools(self._mcp, self._ctx, allowed_tools=at) - aiogram_mcp/permissions.py:44-44 (helper)Permission mapping: 'ban_user' is assigned PermissionLevel.MODERATION in the TOOL_PERMISSIONS dict.
"ban_user": PermissionLevel.MODERATION,