create_role
Create a new role in a Discord server with customizable name, color, permissions, and display options to organize members and manage access.
Instructions
Create a new role in the specified server.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| server_id | No | ||
| color | No | ||
| colour | No | ||
| hoist | No | ||
| mentionable | No | ||
| permissions | No | ||
| permissions_value | No | ||
| unicode_emoji | No | ||
| reason | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- The main handler function for the 'create_role' tool. It fetches the guild, constructs role creation parameters including color conversion and permission parsing, creates the role using Discord API, optionally adjusts position, and returns a success message.
async def handle_create_role(discord_client, arguments: Dict[str, Any]) -> List[TextContent]: """Create a new role""" guild = await discord_client.fetch_guild(int(arguments["server_id"])) kwargs = { "name": arguments["name"], "reason": arguments.get("reason", "Role created via MCP") } if "color" in arguments: kwargs["color"] = hex_to_color(arguments["color"]) if "permissions" in arguments: kwargs["permissions"] = parse_permissions(arguments["permissions"]) if "hoist" in arguments: kwargs["hoist"] = arguments["hoist"] if "mentionable" in arguments: kwargs["mentionable"] = arguments["mentionable"] role = await guild.create_role(**kwargs) # Handle position after creation if "position" in arguments: await role.edit(position=arguments["position"]) return [TextContent( type="text", text=f"Created role '{role.name}' (ID: {role.id}) in {guild.name}" )] - src/discord_mcp/integrated_server.py:276-293 (registration)Registration of the 'create_role' tool in the MCP server's list_tools() function, including the full input schema definition and description.
Tool( name="create_role", description="Create a new role with detailed permissions and appearance", inputSchema={ "type": "object", "properties": { "server_id": {"type": "string", "description": "Server ID"}, "name": {"type": "string", "description": "Role name"}, "color": {"type": "string", "description": "Role color (hex code like #ff0000)"}, "permissions": {"type": "array", "items": {"type": "string"}, "description": "List of permissions"}, "hoist": {"type": "boolean", "description": "Whether role is displayed separately"}, "mentionable": {"type": "boolean", "description": "Whether role is mentionable"}, "position": {"type": "number", "description": "Role position in hierarchy"}, "reason": {"type": "string", "description": "Reason for creation"} }, "required": ["server_id", "name"] } ), - src/discord_mcp/utils.py:10-75 (helper)Helper function parse_permissions used in the handler to convert a list of permission strings into a discord.Permissions object.
def parse_permissions(permission_list: List[str]) -> discord.Permissions: """Convert list of permission strings to discord.Permissions object""" if not permission_list: return discord.Permissions.none() permissions = discord.Permissions.none() # Map common permission names to discord.py attributes permission_mapping = { "administrator": "administrator", "admin": "administrator", "manage_server": "manage_guild", "manage_guild": "manage_guild", "manage_channels": "manage_channels", "manage_roles": "manage_roles", "manage_messages": "manage_messages", "manage_webhooks": "manage_webhooks", "manage_emojis": "manage_emojis_and_stickers", "manage_emojis_and_stickers": "manage_emojis_and_stickers", "kick_members": "kick_members", "ban_members": "ban_members", "create_instant_invite": "create_instant_invite", "view_channels": "view_channel", "view_channel": "view_channel", "send_messages": "send_messages", "send_tts_messages": "send_tts_messages", "embed_links": "embed_links", "attach_files": "attach_files", "read_message_history": "read_message_history", "mention_everyone": "mention_everyone", "use_external_emojis": "external_emojis", "external_emojis": "external_emojis", "add_reactions": "add_reactions", "connect": "connect", "speak": "speak", "mute_members": "mute_members", "deafen_members": "deafen_members", "move_members": "move_members", "use_voice_activation": "use_voice_activation", "priority_speaker": "priority_speaker", "stream": "stream", "change_nickname": "change_nickname", "manage_nicknames": "manage_nicknames", "use_application_commands": "use_application_commands", "request_to_speak": "request_to_speak", "manage_events": "manage_events", "manage_threads": "manage_threads", "create_public_threads": "create_public_threads", "create_private_threads": "create_private_threads", "use_external_stickers": "external_stickers", "send_messages_in_threads": "send_messages_in_threads", "use_embedded_activities": "use_embedded_activities", "moderate_members": "moderate_members" } for perm in permission_list: # Convert to lowercase and handle variations perm_lower = perm.lower().replace(" ", "_").replace("-", "_") # Map the permission discord_perm = permission_mapping.get(perm_lower, perm_lower) if hasattr(permissions, discord_perm): setattr(permissions, discord_perm, True) return permissions - src/discord_mcp/utils.py:77-92 (helper)Helper function hex_to_color used in the handler to convert a hex color string to a discord.Color object.
def hex_to_color(hex_str: str) -> discord.Color: """Convert hex color string to discord.Color""" if not hex_str: return discord.Color.default() # Remove # if present if hex_str.startswith('#'): hex_str = hex_str[1:] try: # Convert hex to integer color_int = int(hex_str, 16) return discord.Color(color_int) except ValueError: # Return default color if conversion fails return discord.Color.default()