discord-mcp

Search guild messages

discord_search_guild_messages

Read-only

Toolset
Messages messages
Discord permission
Read Message History
Context cost
615 tokens, estimated2,460 bytes of definition, divided by 4

Search for messages across all channels in a guild using Discord's native search API. Returns at most 25 messages matching the query with channel context, with no way to page past them. Age-restricted (NSFW) channels are left out. Requires the Read Message History permission and the Message Content privileged intent, enabled in the Developer Portal. While Discord is still building the server's search index, the call fails and says how many seconds to wait. Use discord_search_messages for a substring scan of one channel's last 100 messages. To read the messages around a hit, use discord_read_messages with around.

Risk and annotations

Read-onlyreadOnlyHintyesDoes not modify your server.
DestructivedestructiveHintn/aNot declared: it only applies to tools that write.
IdempotentidempotentHintn/aNot declared.
Open worldopenWorldHintyesInteracts with an external system: Discord.

Annotations are hints the server declares. Clients use them to decide when to ask you before a call.

Parameters

ParameterTypeRulesDescription
guild_idrequiredstring
pattern ^\d{17,20}$
Discord server (guild) ID (snowflake).
queryrequiredstring
none
Search query (case-insensitive).
channel_idoptionalstring
pattern ^\d{17,20}$
Optional. Restrict search to this channel ID.
author_idoptionalstring
pattern ^\d{17,20}$
Optional. Only show messages from this user ID.
limitoptionalinteger
1 to 25default 25
Max messages to return (1–25). Default 25.

Output

Declared by outputSchema: clients receive this shape as structuredContent.

FieldTypeDescription
matchesrequiredarray of objects
id (nested, level 1)requiredstring
author (nested, level 1)requiredstring
author_id (nested, level 1)requiredstring
webhook_id (nested, level 1)string
content (nested, level 1)requiredstring
timestamp (nested, level 1)requiredstring
embeds (nested, level 1)array of objects
title (nested, level 2)string
author (nested, level 2)string
description (nested, level 2)string
url (nested, level 2)string
fields (nested, level 2)array of objects
name (nested, level 3)requiredstring
value (nested, level 3)requiredstring
moreFields (nested, level 2)numberCount of fields left out past the first 10. Absent when none were.
footer (nested, level 2)string
channel_id (nested, level 1)requiredstring
channel_name (nested, level 1)requiredstring

Related tools

Named in its description

Also in Messages

Raw definition (2,460 bytes)
{
  "name": "discord_search_guild_messages",
  "description": "Search for messages across all channels in a guild using Discord's native search API. Returns at most 25 messages matching the query with channel context, with no way to page past them. Age-restricted (NSFW) channels are left out. Requires the Read Message History permission and the Message Content privileged intent, enabled in the Developer Portal. While Discord is still building the server's search index, the call fails and says how many seconds to wait. Use discord_search_messages for a substring scan of one channel's last 100 messages. To read the messages around a hit, use discord_read_messages with around.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "guild_id": {
        "type": "string",
        "pattern": "^\\d{17,20}$",
        "description": "Discord server (guild) ID (snowflake)."
      },
      "query": {
        "type": "string",
        "description": "Search query (case-insensitive)."
      },
      "channel_id": {
        "description": "Optional. Restrict search to this channel ID.",
        "type": "string",
        "pattern": "^\\d{17,20}$"
      },
      "author_id": {
        "description": "Optional. Only show messages from this user ID.",
        "type": "string",
        "pattern": "^\\d{17,20}$"
      },
      "limit": {
        "default": 25,
        "description": "Max messages to return (1–25). Default 25.",
        "type": "integer",
        "minimum": 1,
        "maximum": 25
      }
    },
    "required": [
      "guild_id",
      "query"
    ],
    "additionalProperties": false
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "matches": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "author": {
              "type": "string"
            },
            "author_id": {
              "type": "string"
            },
            "webhook_id": {
              "type": "string"
            },
            "content": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            },
            "embeds": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string"
                  },
                  "author": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "url": {
                    "type": "string"
                  },
                  "fields": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "value": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "name",
                        "value"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "moreFields": {
                    "description": "Count of fields left out past the first 10. Absent when none were.",
                    "type": "number"
                  },
                  "footer": {
                    "type": "string"
                  }
                },
                "additionalProperties": false
              }
            },
            "channel_id": {
              "type": "string"
            },
            "channel_name": {
              "type": "string"
            }
          },
          "required": [
            "id",
            "author",
            "author_id",
            "content",
            "timestamp",
            "channel_id",
            "channel_name"
          ],
          "additionalProperties": false
        }
      }
    },
    "required": [
      "matches"
    ],
    "additionalProperties": false
  },
  "annotations": {
    "title": "Search guild messages",
    "readOnlyHint": true,
    "openWorldHint": true
  }
}