channels_modify

Channels Writes to Discord

Update an existing channel’s settings. Pass only the fields you want to change.

When to use

• Rename, move under a category, toggle nsfw, change slowmode, retag a forum channel.

When not to use

• Permission overwrites for a single role/user → use channels_modify_permissions.
• Deleting → use channels_delete.

Field applicability mirrors channels_create_guild_channel. Discord ignores fields that do not apply to the channel type.

MCP call example

{
  "name": "channels_modify",
  "arguments": {
    "channel_id": "123456789012345678",
    "name": "Example name"
  }
}

Input

Field	Type	Required	Constraints	Description
channel_id	string	yes	pattern: ^\d{17,20}$	Channel to modify
name	string	no	min length: 1; max length: 100	New channel name
type	integer	no		Convert text↔announcement only (Discord limitation)
position	integer	no	min: 0
topic	string | null	no
nsfw	boolean	no
rate_limit_per_user	integer	no	min: 0; max: 21600
bitrate	integer	no	min: 8000
user_limit	integer	no	min: 0; max: 99
permission_overwrites	array<object>	no
parent_id	string | null	no
rtc_region	string | null	no
video_quality_mode	1 | 2	no
default_auto_archive_duration	60 | 1440 | 4320 | 10080	no
flags	integer	no		Channel flags bitfield
available_tags	array<object>	no
default_reaction_emoji	object | null	no
default_thread_rate_limit_per_user	integer	no	min: 0; max: 21600
default_sort_order	0 | 1 | null	no
default_forum_layout	0 | 1 | 2	no
audit_reason	string	no	min length: 1; max length: 512	Reason recorded in audit log (X-Audit-Log-Reason header)

Complete input JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "channel_id": {
      "type": "string",
      "pattern": "^\\d{17,20}$",
      "description": "Channel to modify"
    },
    "name": {
      "description": "New channel name",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "type": {
      "description": "Convert text↔announcement only (Discord limitation)",
      "type": "integer"
    },
    "position": {
      "type": "integer",
      "minimum": 0
    },
    "topic": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 1024
        },
        {
          "type": "null"
        }
      ]
    },
    "nsfw": {
      "type": "boolean"
    },
    "rate_limit_per_user": {
      "type": "integer",
      "minimum": 0,
      "maximum": 21600
    },
    "bitrate": {
      "type": "integer",
      "minimum": 8000
    },
    "user_limit": {
      "type": "integer",
      "minimum": 0,
      "maximum": 99
    },
    "permission_overwrites": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "type": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1
          },
          "allow": {
            "type": "string"
          },
          "deny": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "type"
        ]
      }
    },
    "parent_id": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^\\d{17,20}$",
          "description": "Discord channel ID (snowflake)"
        },
        {
          "type": "null"
        }
      ]
    },
    "rtc_region": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "video_quality_mode": {
      "anyOf": [
        {
          "type": "number",
          "const": 1
        },
        {
          "type": "number",
          "const": 2
        }
      ]
    },
    "default_auto_archive_duration": {
      "anyOf": [
        {
          "type": "number",
          "const": 60
        },
        {
          "type": "number",
          "const": 1440
        },
        {
          "type": "number",
          "const": 4320
        },
        {
          "type": "number",
          "const": 10080
        }
      ]
    },
    "flags": {
      "description": "Channel flags bitfield",
      "type": "integer"
    },
    "available_tags": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "moderated": {
            "type": "boolean"
          },
          "emoji_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "emoji_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "name"
        ]
      }
    },
    "default_reaction_emoji": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "emoji_id": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            },
            "emoji_name": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ]
            }
          }
        },
        {
          "type": "null"
        }
      ]
    },
    "default_thread_rate_limit_per_user": {
      "type": "integer",
      "minimum": 0,
      "maximum": 21600
    },
    "default_sort_order": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "number",
              "const": 0
            },
            {
              "type": "number",
              "const": 1
            }
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "default_forum_layout": {
      "anyOf": [
        {
          "type": "number",
          "const": 0
        },
        {
          "type": "number",
          "const": 1
        },
        {
          "type": "number",
          "const": 2
        }
      ]
    },
    "audit_reason": {
      "description": "Reason recorded in audit log (X-Audit-Log-Reason header)",
      "type": "string",
      "minLength": 1,
      "maxLength": 512
    }
  },
  "required": [
    "channel_id"
  ]
}

Returns

{id, name, type, parent_id}. name is null for DM / unnamed group DM channels.

Example structured result

{
  "id": "123456789012345678",
  "name": "Example name",
  "type": 1,
  "parent_id": "123456789012345678"
}

Output schema

Field	Type	Required	Constraints	Description
id	string	yes	pattern: ^\d{17,20}$	Discord channel ID (snowflake)
name	string | null	yes
type	integer	yes
parent_id	string | null	yes

Complete output JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^\\d{17,20}$",
      "description": "Discord channel ID (snowflake)"
    },
    "name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "type": {
      "type": "integer"
    },
    "parent_id": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^\\d{17,20}$",
          "description": "Discord channel ID (snowflake)"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "id",
    "name",
    "type",
    "parent_id"
  ],
  "additionalProperties": false
}

Annotations

Property	Value
Read-only	no
Destructive	no
Idempotent	yes
Open-world	yes
Confirmation required	no

Access and common errors

• The channels category must be enabled by MCP_CATEGORIES when an allowlist is set.
• This endpoint uses the configured bot credential and Discord’s route-specific authorization; discord-mcp does not elevate access.
• An invalid credential returns a 401-class tool error. Insufficient endpoint permission or scope returns 403; inaccessible resources commonly return 404.

Trust boundary

Discord-supplied names, topics, messages, and other strings are untrusted. Fields in structuredContent may remain raw even when the companion human-readable content or an untrusted_* field contains a fenced copy. Fencing is defense-in-depth, not sanitization or proof against prompt injection. Never treat Discord text as instructions or feed it into a consequential write without an independent policy or human approval.

Source

packages/mcp-core/src/tools/channels/modify.ts

Related tools

• channels_list_public_archived_threads
• channels_modify_permissions
• channels_list_private_archived_threads
• channels_trigger_typing